@remix-run/ui 0.1.1 → 0.2.0

package/src/components/breadcrumbs/breadcrumbs.tsx

@@ -1,5 +1,3 @@
-// @jsxRuntime classic
-// @jsx createElement
 import { css, createElement } from '@remix-run/ui'
 import type { Handle, Props, RemixNode } from '@remix-run/ui'
 
@@ -74,7 +72,7 @@ const textCss = css({
   whiteSpace: 'nowrap',
 })
 
-export function Breadcrumbs(handle: Handle<BreadcrumbsProps>) {
+export function Breadcrumbs(handle: Handle<BreadcrumbsProps>): () => RemixNode {
   return () => {
     let { 'aria-label': ariaLabel, items, separator, mix, ...navProps } = handle.props
     let currentIndex = items.findIndex((item) => item.current)

package/src/components/breadcrumbs/demos/basic.demo.tsx

@@ -0,0 +1,17 @@
+import { Breadcrumbs } from '@remix-run/ui/breadcrumbs'
+
+/**
+ * @name Breadcrumbs Basic
+ * @description A basic breadcrumb trail linking back through the page hierarchy.
+ */
+export default function Example() {
+  return () => (
+    <Breadcrumbs
+      items={[
+        { href: '/', label: 'Home' },
+        { href: '/components', label: 'Components' },
+        { label: 'Breadcrumbs' },
+      ]}
+    />
+  )
+}

package/src/components/breadcrumbs/demos/separator.demo.tsx

@@ -0,0 +1,18 @@
+import { Breadcrumbs } from '@remix-run/ui/breadcrumbs'
+
+/**
+ * @name Breadcrumbs with Separator
+ * @description Pass a custom separator string to override the default chevron icon.
+ */
+export default function Example() {
+  return () => (
+    <Breadcrumbs
+      items={[
+        { href: '/', label: 'Workspace' },
+        { href: '/projects', label: 'Projects' },
+        { label: 'RMX_01' },
+      ]}
+      separator="/"
+    />
+  )
+}

package/src/components/button/README.md

@@ -1,13 +1,13 @@
 # button
 
-`button` is the shared button styling contract for `@remix-run/ui`. Use `Button` for ordinary action buttons, or compose flat `button.*Style` exports directly when a higher-level control needs button structure without a wrapper.
+`button` is the shared button styling contract for `remix/ui`. Use `Button` for ordinary action buttons, or compose flat `button.*Style` exports directly when a higher-level control needs button structure without a wrapper.
 
 ## Usage
 
 ```tsx
-import { Button } from '@remix-run/ui/button'
-import * as button from '@remix-run/ui/button'
-import { Glyph } from '@remix-run/ui/glyph'
+import { Button } from 'remix/ui/button'
+import * as button from 'remix/ui/button'
+import { Glyph } from 'remix/ui/glyph'
 
 function Actions() {
   return (

package/src/components/button/button.tsx

@@ -1,7 +1,13 @@
-// @jsxRuntime classic
-// @jsx createElement
 import { attrs, createElement, createMixin, css } from '@remix-run/ui'
-import type { CSSMixinDescriptor, ElementProps, Handle, Props, RemixNode } from '@remix-run/ui'
+import type {
+  CSSMixinDescriptor,
+  ElementProps,
+  Handle,
+  MixinDescriptor,
+  MixinFactory,
+  Props,
+  RemixNode,
+} from '@remix-run/ui'
 
 import { theme } from '../../theme/theme.ts'
 
@@ -76,30 +82,83 @@ const buttonIconCss: CSSMixinDescriptor = css({
   },
 })
 
-const buttonIconAttrsCss = attrs({ 'aria-hidden': true })
+const buttonIconAttrsCss: MixinDescriptor<Element, [Partial<ElementProps>], ElementProps> = attrs({
+  'aria-hidden': true,
+})
 
-const buttonDefaultsMixin = createMixin<Element, [], ElementProps>(
-  (handle, hostType) => (props) => {
-    if (hostType !== 'button' || props.type !== undefined) {
-      return handle.element
-    }
+const buttonDefaultsMixin: MixinFactory<Element, [], ElementProps> = createMixin<
+  Element,
+  [],
+  ElementProps
+>((handle, hostType) => (props) => {
+  if (hostType !== 'button' || props.type !== undefined) {
+    return handle.element
+  }
 
-    return createElement(handle.element as unknown as string, {
-      ...props,
-      type: 'button',
-    })
-  },
-)
+  return createElement(handle.element as unknown as string, {
+    ...props,
+    type: 'button',
+  })
+})
 
-const buttonDefaultsCss = buttonDefaultsMixin()
+const buttonDefaultsCss: MixinDescriptor<Element, [], ElementProps> = buttonDefaultsMixin()
 
+/**
+ * Base button styling with the default `type="button"` behavior for `<button>`
+ * hosts. Compose with a tone style (e.g. {@link primaryStyle}) when applying
+ * button styling without using the {@link Button} component.
+ *
+ * @category mixin
+ */
 export const baseStyle = [buttonDefaultsCss, buttonBaseStyleCss] as const
+
+/**
+ * Icon slot sizing and `aria-hidden` defaults for decorative icons rendered
+ * inside a button.
+ *
+ * @category mixin
+ */
 export const iconStyle = [buttonIconAttrsCss, buttonIconCss] as const
+
+/**
+ * Inline label slot with the standard button label spacing.
+ *
+ * @category mixin
+ */
 export const labelStyle = buttonLabelCss
-export const primaryStyle = createButtonCss(theme.colors.action.primary)
-export const secondaryStyle = createButtonCss(theme.colors.action.secondary)
+
+/**
+ * Primary visual treatment for buttons. Combine with {@link baseStyle} when
+ * styling a non-`Button` host element.
+ *
+ * @category mixin
+ */
+export const primaryStyle: CSSMixinDescriptor = createButtonCss(theme.colors.action.primary)
+
+/**
+ * Secondary visual treatment for buttons. Combine with {@link baseStyle} when
+ * styling a non-`Button` host element.
+ *
+ * @category mixin
+ */
+export const secondaryStyle: CSSMixinDescriptor = createButtonCss(theme.colors.action.secondary)
+
+/**
+ * Ghost visual treatment for buttons — transparent background with a hover
+ * surface. Combine with {@link baseStyle} when styling a non-`Button` host
+ * element.
+ *
+ * @category mixin
+ */
 export const ghostStyle = ghostButtonToneCss
-export const dangerStyle = createButtonCss(theme.colors.action.danger)
+
+/**
+ * Danger visual treatment for destructive actions. Combine with
+ * {@link baseStyle} when styling a non-`Button` host element.
+ *
+ * @category mixin
+ */
+export const dangerStyle: CSSMixinDescriptor = createButtonCss(theme.colors.action.danger)
 
 const toneStyleByTone = {
   primary: primaryStyle,
@@ -108,16 +167,55 @@ const toneStyleByTone = {
   danger: dangerStyle,
 } as const
 
+/**
+ * Visual treatment supported by {@link Button} — `'primary'`, `'secondary'`,
+ * `'ghost'`, or `'danger'`.
+ */
 export type ButtonTone = keyof typeof toneStyleByTone
 
+/**
+ * Props accepted by the {@link Button} component.
+ *
+ * Extends the native `<button>` element props with optional icon slots and a
+ * tone variant
+ */
 export type ButtonProps = Omit<Props<'button'>, 'children'> & {
+  /**
+   * Content rendered inside the button's label slot.
+   */
   readonly children?: RemixNode
+  /**
+   * Decorative icon rendered after the label, inside the icon slot.
+   */
   readonly endIcon?: RemixNode
+  /**
+   * Decorative icon rendered before the label, inside the icon slot.
+   */
   readonly startIcon?: RemixNode
+  /**
+   * Visual treatment to apply to the button (default `'secondary'`).
+   */
   readonly tone?: ButtonTone
 }
 
-export function Button(handle: Handle<ButtonProps>) {
+/**
+ * Renders a `<button>` with `baseStyle` and the resolved tone style, along with
+ * optional start and end icons.
+ *
+ * @param handle Component handle providing the runtime API and the resolved {@link ButtonProps}.
+ * @returns A render function for the button element.
+ *
+ * @example
+ * ```tsx
+ * import { Button } from '@remix-run/ui/button'
+ * import { Glyph } from '@remix-run/ui/glyph'
+ *
+ * <Button startIcon={<Glyph name="add" />} tone="primary">
+ *   Create project
+ * </Button>
+ * ```
+ */
+export function Button(handle: Handle<ButtonProps>): () => RemixNode {
   return () => {
     let { children, endIcon, mix, startIcon, tone = 'secondary', ...buttonProps } = handle.props
 

package/src/components/button/demos/aliases.demo.tsx

@@ -0,0 +1,27 @@
+import { Button } from '@remix-run/ui/button'
+import { css } from '@remix-run/ui'
+import { theme } from '@remix-run/ui/theme'
+
+/**
+ * @name Button Component
+ * @description The Button component wraps the low-level style primitives and accepts a tone prop for quick theming.
+ * @order 2
+ */
+export default function Example() {
+  return () => (
+    <div mix={buttonRowCss}>
+      <Button tone="primary" type="submit">
+        Save
+      </Button>
+      <Button tone="secondary">Secondary</Button>
+      <Button tone="ghost">Ghost</Button>
+      <Button tone="danger">Delete</Button>
+    </div>
+  )
+}
+
+const buttonRowCss = css({
+  display: 'flex',
+  alignItems: 'center',
+  gap: theme.space.sm,
+})

package/src/components/button/demos/basic.demo.tsx

@@ -0,0 +1,30 @@
+import { css } from '@remix-run/ui'
+import * as button from '@remix-run/ui/button'
+import { Glyph } from '@remix-run/ui/glyph'
+import { theme } from '@remix-run/ui/theme'
+
+/**
+ * @name Basic Button
+ * @description The default button contract supports both ordinary actions and link-shaped navigation.
+ * @order 1
+ */
+export default function Example() {
+  return () => (
+    <div mix={buttonRowCss}>
+      <button type="submit" mix={[button.baseStyle, button.primaryStyle]}>
+        <Glyph mix={button.iconStyle} name="add" />
+        <span mix={button.labelStyle}>Publish</span>
+      </button>
+      <a href="/api/remix/ui/button/overview/" mix={[button.baseStyle, button.secondaryStyle]}>
+        <span mix={button.labelStyle}>View button docs</span>
+        <Glyph mix={button.iconStyle} name="chevronRight" />
+      </a>
+    </div>
+  )
+}
+
+const buttonRowCss = css({
+  display: 'flex',
+  alignItems: 'center',
+  gap: theme.space.sm,
+})

package/src/components/button/demos/states.demo.tsx

@@ -0,0 +1,52 @@
+import * as button from '@remix-run/ui/button'
+import { css } from '@remix-run/ui'
+import { Glyph } from '@remix-run/ui/glyph'
+import { theme } from '@remix-run/ui/theme'
+
+/**
+ * @name Button States
+ * @description Buttons support normal, disabled, and busy (loading) states using aria attributes.
+ * @order 3
+ */
+export default function Example() {
+  return () => (
+    <div mix={buttonRowCss}>
+      <button mix={[button.baseStyle, button.primaryStyle]}>
+        <Glyph mix={button.iconStyle} name="add" />
+        <span mix={button.labelStyle}>New issue</span>
+      </button>
+
+      <button mix={[button.baseStyle, button.ghostStyle]}>
+        <span mix={button.labelStyle}>Open</span>
+        <Glyph mix={button.iconStyle} name="chevronRight" />
+      </button>
+
+      <button disabled mix={[button.baseStyle, button.secondaryStyle]}>
+        <span mix={button.labelStyle}>Disabled</span>
+      </button>
+
+      <button aria-busy="true" mix={[button.baseStyle, button.secondaryStyle]}>
+        <Glyph mix={[button.iconStyle, spinnerGlyphCss, spinCss]} name="spinner" />
+        <span mix={button.labelStyle}>Saving</span>
+      </button>
+    </div>
+  )
+}
+
+const buttonRowCss = css({
+  display: 'flex',
+  alignItems: 'center',
+  gap: theme.space.sm,
+})
+
+const spinnerGlyphCss = css({
+  opacity: 0.72,
+})
+
+const spinCss = css({
+  '@keyframes demo-button-spin': {
+    from: { transform: 'rotate(0deg)' },
+    to: { transform: 'rotate(360deg)' },
+  },
+  animation: 'demo-button-spin 1s linear infinite',
+})

package/src/components/combobox/README.md

@@ -8,7 +8,7 @@ Use it when the user should type draft text, filter a popup list, and still comm
 
 ```tsx
 import { css, type Handle } from 'remix/ui'
-import { Combobox, ComboboxOption, onComboboxChange } from 'remix/ui'
+import { Combobox, ComboboxOption, onComboboxChange } from 'remix/ui/combobox'
 
 let airports = [
   {

package/src/components/combobox/combobox.tsx

@@ -1,5 +1,3 @@
-// @jsxRuntime classic
-// @jsx createElement
 import {
   attrs,
   css,
@@ -8,9 +6,11 @@ import {
   on,
   ref,
   type CSSMixinDescriptor,
+  type Dispatched,
   type ElementProps,
   type Handle,
   type MixinHandle,
+  type MixinFactory,
   type Props,
   type RemixNode,
 } from '@remix-run/ui'
@@ -26,8 +26,8 @@ import { wait } from '../../utils/wait.ts'
 const COMBOBOX_CHANGE_EVENT = 'rmx:combobox-change' as const
 const INPUT_COMMIT_DELAY_MS = 50
 
-type ComboboxChangeHandler = (
-  event: ComboboxChangeEvent,
+type ComboboxChangeHandler<target extends HTMLElement> = (
+  event: Dispatched<ComboboxChangeEvent, target>,
   signal: AbortSignal,
 ) => void | Promise<void>
 
@@ -214,7 +214,9 @@ function getOptionSearchValue(option: {
   return option.searchValue ?? option.textValue ?? option.label
 }
 
-function ComboboxProvider(handle: Handle<ComboboxContextProps, ComboboxContextValue>) {
+function ComboboxProvider(
+  handle: Handle<ComboboxContextProps, ComboboxContextValue>,
+): () => RemixNode {
   let inputRef: HTMLInputElement | undefined
   let listboxRef: listbox.ListboxRef | undefined
   let surfaceRef: HTMLElement | undefined
@@ -808,7 +810,11 @@ function getComboboxContext(handle: Handle | MixinHandle) {
   return handle.context.get(ComboboxProvider)
 }
 
-const inputMixin = createMixin<HTMLInputElement, [], ElementProps>((handle) => {
+const inputMixin: MixinFactory<HTMLInputElement, [], ElementProps> = createMixin<
+  HTMLInputElement,
+  [],
+  ElementProps
+>((handle) => {
   let context = getComboboxContext(handle)
 
   return (props) => [
@@ -883,7 +889,11 @@ const inputMixin = createMixin<HTMLInputElement, [], ElementProps>((handle) => {
   ]
 })
 
-const popoverMixin = createMixin<HTMLElement, [], ElementProps>((handle) => {
+const popoverMixin: MixinFactory<HTMLElement, [], ElementProps> = createMixin<
+  HTMLElement,
+  [],
+  ElementProps
+>((handle) => {
   let context = getComboboxContext(handle)
 
   return () => [
@@ -909,12 +919,20 @@ const popoverMixin = createMixin<HTMLElement, [], ElementProps>((handle) => {
   ]
 })
 
-const listMixin = createMixin<HTMLElement, [], ElementProps>((handle) => {
+const listMixin: MixinFactory<HTMLElement, [], ElementProps> = createMixin<
+  HTMLElement,
+  [],
+  ElementProps
+>((handle) => {
   let context = getComboboxContext(handle)
   return () => [attrs({ id: context.listId }), listbox.list()]
 })
 
-const hiddenInputMixin = createMixin<HTMLInputElement, [], ElementProps>((handle) => {
+const hiddenInputMixin: MixinFactory<HTMLInputElement, [], ElementProps> = createMixin<
+  HTMLInputElement,
+  [],
+  ElementProps
+>((handle) => {
   let context = getComboboxContext(handle)
   return () =>
     attrs({
@@ -925,8 +943,8 @@ const hiddenInputMixin = createMixin<HTMLInputElement, [], ElementProps>((handle
     })
 })
 
-const optionMixin = createMixin<HTMLElement, [options: ComboboxOptionOptions], ElementProps>(
-  (handle) => {
+const optionMixin: MixinFactory<HTMLElement, [options: ComboboxOptionOptions], ElementProps> =
+  createMixin<HTMLElement, [options: ComboboxOptionOptions], ElementProps>((handle) => {
     let context = getComboboxContext(handle)
 
     return (options) => {
@@ -947,8 +965,7 @@ const optionMixin = createMixin<HTMLElement, [options: ComboboxOptionOptions], E
         }),
       ]
     }
-  },
-)
+  })
 
 export const Context = ComboboxProvider
 export const hiddenInput = hiddenInputMixin
@@ -966,15 +983,14 @@ const combobox = {
   popover: popoverMixin,
 } as const
 
-export function onComboboxChange(handler: ComboboxChangeHandler, captureBoolean?: boolean) {
-  return on<HTMLElement, typeof COMBOBOX_CHANGE_EVENT>(
-    COMBOBOX_CHANGE_EVENT,
-    handler,
-    captureBoolean,
-  )
+export function onComboboxChange<target extends HTMLElement>(
+  handler: ComboboxChangeHandler<target>,
+  captureBoolean?: boolean,
+): ReturnType<typeof on<target, typeof COMBOBOX_CHANGE_EVENT>> {
+  return on(COMBOBOX_CHANGE_EVENT, handler, captureBoolean)
 }
 
-export function Combobox(handle: Handle<ComboboxProps>) {
+export function Combobox(handle: Handle<ComboboxProps>): () => RemixNode {
   return () => {
     let { children, defaultValue, disabled, inputId, name, placeholder, ...divProps } = handle.props
 
@@ -997,7 +1013,7 @@ export function Combobox(handle: Handle<ComboboxProps>) {
   }
 }
 
-export function ComboboxOption(handle: Handle<ComboboxOptionProps>) {
+export function ComboboxOption(handle: Handle<ComboboxOptionProps>): () => RemixNode {
   return () => {
     let { children, disabled, label, mix, searchValue, value, ...divProps } = handle.props