@chassis-ui/react 0.0.0-20260831090525

package/src/components/table/TableCell.tsx

@@ -0,0 +1,27 @@
+import { ReactElement, ReactNode } from 'react'
+import { Cell } from 'react-stately'
+
+export interface TableCellProps {
+  /**
+   * The contents of the cell.
+   */
+  children: ReactNode
+  /**
+   * A string of all className you want applied to the cell.
+   */
+  className?: string
+  /**
+   * Indicates how many columns the cell spans.
+   */
+  colSpan?: number
+  /**
+   * A string representation of the cell's contents, used for typeahead.
+   */
+  textValue?: string
+}
+
+/**
+ * Collection node, data-only — see `TableHeader`. Read by `Table` to build a cell in the
+ * table's collection; never rendered directly.
+ */
+export const TableCell = Cell as unknown as (props: TableCellProps) => ReactElement

package/src/components/table/TableColumn.tsx

@@ -0,0 +1,31 @@
+import { ReactElement, ReactNode } from 'react'
+import { Column } from 'react-stately'
+
+export interface TableColumnProps {
+  /**
+   * Whether the column allows sorting. Adds a sort indicator and makes the header
+   * clickable/keyboard-activatable.
+   */
+  allowsSorting?: boolean
+  /**
+   * Rendered contents of the column header.
+   */
+  children: ReactNode
+  /**
+   * A string of all className you want applied to the column header.
+   */
+  className?: string
+  /**
+   * A string representation of the column header, used for accessibility announcements and,
+   * when `Table`'s `stacked` prop is set, as the label shown before each row's value for this
+   * column. Defaults to `children` when it's a plain string — set this explicitly when the
+   * header contains anything else (an icon, a `Tooltip`, etc.).
+   */
+  textValue?: string
+}
+
+/**
+ * Collection node, data-only — see `TableHeader`. Read by `Table` to build a column in the
+ * table's collection; never rendered directly.
+ */
+export const TableColumn = Column as unknown as (props: TableColumnProps) => ReactElement

package/src/components/table/TableHeader.tsx

@@ -0,0 +1,26 @@
+import { ReactElement } from 'react'
+import { TableHeader as StatelyTableHeader } from 'react-stately'
+
+export interface TableHeaderProps<T> {
+  /**
+   * `TableColumn` elements, or a render function paired with `columns` for dynamic column
+   * generation.
+   */
+  children: ReactElement | ReactElement[] | ((column: T) => ReactElement)
+  /**
+   * A string of all className you want applied to the `<thead>` element.
+   */
+  className?: string
+  /**
+   * A list of column data objects, rendered via the function form of `children`.
+   */
+  columns?: readonly T[]
+}
+
+/**
+ * Collection node, data-only — read by `Table` to build the table's column collection. Never
+ * rendered directly.
+ */
+export const TableHeader = StatelyTableHeader as unknown as <T>(
+  props: TableHeaderProps<T>
+) => ReactElement

package/src/components/table/TableRow.tsx

@@ -0,0 +1,24 @@
+import { Key, ReactElement } from 'react'
+import { Row } from 'react-stately'
+
+export interface TableRowProps {
+  /**
+   * `TableCell` elements, or a render function called once per column with that column's key —
+   * required when the row's parent `TableBody` uses the `items`/render-function form.
+   */
+  children: ReactElement | ReactElement[] | ((columnKey: Key) => ReactElement)
+  /**
+   * A string of all className you want applied to the row.
+   */
+  className?: string
+  /**
+   * A string representation of the row's contents, used for typeahead.
+   */
+  textValue?: string
+}
+
+/**
+ * Collection node, data-only — see `TableHeader`. Read by `Table` to build a row in the
+ * table's collection; never rendered directly.
+ */
+export const TableRow = Row as unknown as (props: TableRowProps) => ReactElement

package/src/components/table/index.ts

@@ -0,0 +1,12 @@
+export { Table } from './Table'
+export type { TableProps } from './Table'
+export { TableBody } from './TableBody'
+export type { TableBodyProps } from './TableBody'
+export { TableCell } from './TableCell'
+export type { TableCellProps } from './TableCell'
+export { TableColumn } from './TableColumn'
+export type { TableColumnProps } from './TableColumn'
+export { TableHeader } from './TableHeader'
+export type { TableHeaderProps } from './TableHeader'
+export { TableRow } from './TableRow'
+export type { TableRowProps } from './TableRow'

package/src/components/tabs/Tab.tsx

@@ -0,0 +1,36 @@
+import { ReactNode } from 'react'
+import { Key } from 'react-stately'
+
+export interface TabProps {
+  /**
+   * Label content for the tab. Must be a plain string for it to be used as the tab's accessible
+   * name when the rendered content itself doesn't expose one (e.g. an icon-only tab).
+   */
+  children: ReactNode
+  /**
+   * Prevents the tab from being selected, focused, or otherwise interacted with.
+   */
+  disabled?: boolean
+  /**
+   * Identifies this tab and pairs it with the `TabPanel` of the same `id`.
+   */
+  id: Key
+}
+
+// `Tab` is never actually mounted — it's read as data by `Tabs`, which builds react-aria's tab
+// collection from each `Tab`'s `id` and `children` (see `Tabs.tsx`), and `TabList` renders the
+// real, focusable tab elements from that collection instead. This keeps the public authoring
+// shape as plain composed JSX:
+//
+//   <TabList aria-label="...">
+//     <Tab id="home">Home</Tab>
+//     <Tab id="profile">Profile</Tab>
+//   </TabList>
+//   <TabPanel id="home">...</TabPanel>
+//   <TabPanel id="profile">...</TabPanel>
+//
+// `id` (not React's own `key`) is what pairs a tab with its panel — still give each `Tab`/
+// `TabPanel` a React `key` too, as you would for any list.
+export const Tab = (_props: TabProps): null => null
+
+Tab.displayName = 'Tab'

package/src/components/tabs/TabList.tsx

@@ -0,0 +1,76 @@
+import React, { AriaAttributes, forwardRef, ReactElement, ReactNode, useRef } from 'react'
+import classNames from 'classnames'
+import { useTab, useTabList } from 'react-aria'
+import { Node } from 'react-stately'
+
+import { useForkedRef } from '../../hooks'
+import { TabProps } from './Tab'
+import { useTabsContext } from './context'
+
+export interface TabListProps extends AriaAttributes {
+  /**
+   * `Tab` elements — read as data by `Tabs` to build the tab collection (see `Tabs.tsx`). Not
+   * rendered directly.
+   */
+  children: ReactNode
+  /**
+   * A string of all className you want applied to the base component.
+   */
+  className?: string
+  /**
+   * Set the tab list variant to tabs or pills.
+   */
+  variant?: 'tabs' | 'pills'
+}
+
+// Renders the actual, focusable tabs from `state.collection` — built by the ancestor `Tabs`
+// from this component's own `children` (see the comment there). This component's own `children`
+// prop is intentionally unused for rendering.
+export const TabList = forwardRef<HTMLUListElement, TabListProps>(
+  ({ className, variant = 'tabs', ...rest }, ref) => {
+    const { keyboardActivation, orientation, state } = useTabsContext()
+    const listRef = useRef<HTMLUListElement>(null)
+    const forkedRef = useForkedRef(ref, listRef)
+    const { tabListProps } = useTabList(
+      { keyboardActivation, orientation, ...rest },
+      state,
+      listRef
+    )
+
+    const _className = classNames('nav', `nav-${variant}`, className)
+
+    return (
+      <ul className={_className} {...tabListProps} ref={forkedRef}>
+        {[...state.collection].map((item) => (
+          <TabItem key={item.key} item={item} />
+        ))}
+      </ul>
+    )
+  }
+)
+
+TabList.displayName = 'TabList'
+
+interface TabItemProps {
+  item: Node<ReactElement<TabProps>>
+}
+
+const TabItem = ({ item }: TabItemProps) => {
+  const { state } = useTabsContext()
+  const ref = useRef<HTMLAnchorElement>(null)
+  const { tabProps, isSelected, isDisabled } = useTab({ key: item.key }, state, ref)
+
+  return (
+    // ARIA's `tablist` role only permits `tab`-role children — `role="presentation"` opts this
+    // `<li>` wrapper out without hiding its content, same pattern as `MenuHeader`.
+    <li className="nav-item" role="presentation">
+      <a
+        className={classNames('nav-link', { active: isSelected, disabled: isDisabled })}
+        {...tabProps}
+        ref={ref}
+      >
+        {item.rendered}
+      </a>
+    </li>
+  )
+}

package/src/components/tabs/TabPanel.tsx

@@ -0,0 +1,68 @@
+import React, { forwardRef, HTMLAttributes, ReactNode, useRef } from 'react'
+import classNames from 'classnames'
+import { useTabPanel } from 'react-aria'
+import { Key } from 'react-stately'
+import { Transition } from 'react-transition-group'
+
+import { useForkedRef } from '../../hooks'
+import { useTabsContext } from './context'
+
+export interface TabPanelProps extends Omit<HTMLAttributes<HTMLDivElement>, 'id'> {
+  /**
+   * Content of the panel, shown while the `Tab` of the same `id` is selected.
+   */
+  children: ReactNode
+  /**
+   * A string of all className you want applied to the base component.
+   */
+  className?: string
+  /**
+   * Pairs this panel with the `Tab` of the same `id`.
+   */
+  id: Key
+}
+
+// The counterpart to `Tab` — unlike `Tab`, `TabPanel` renders for real, but only while its `id`
+// matches the currently selected tab, and unmounts immediately (not staggered) once it isn't.
+// chassis-css's `.tab-content > .tab-pane`/`.active` rule (`_transitions.scss`) assumes exactly
+// one visible block-level panel at a time — there's no overlap/positioning support for a second
+// panel to occupy the same space while it exits, so staggering the *outgoing* panel's removal
+// would leave two full-height panels stacked in flow simultaneously and visibly shove the layout
+// around. Only the *incoming* panel gets a transition: `Transition`'s `appear` flag makes its
+// mount start a render frame without the `show` class — `fade` alone means `opacity: 0` —
+// before adding it a tick later, so the panel fades in instead of popping straight to full
+// opacity. `appear` is gated on `isInitialSelectionRef` so only an actual tab *switch* animates,
+// not whichever panel happens to be selected on first paint.
+export const TabPanel = forwardRef<HTMLDivElement, TabPanelProps>(
+  ({ children, className, id, ...rest }, ref) => {
+    const { state, isInitialSelectionRef } = useTabsContext()
+    const panelRef = useRef<HTMLDivElement>(null)
+    const forkedRef = useForkedRef(ref, panelRef)
+    const { tabPanelProps } = useTabPanel({ id }, state, panelRef)
+
+    if (state.selectedKey !== id) return null
+
+    return (
+      <Transition in appear={!isInitialSelectionRef.current} nodeRef={panelRef} timeout={150}>
+        {(transitionState) => (
+          <div
+            className={classNames(
+              'tab-pane',
+              'fade',
+              'active',
+              { show: transitionState === 'entered' },
+              className
+            )}
+            {...tabPanelProps}
+            {...rest}
+            ref={forkedRef}
+          >
+            {children}
+          </div>
+        )}
+      </Transition>
+    )
+  }
+)
+
+TabPanel.displayName = 'TabPanel'

package/src/components/tabs/Tabs.tsx

@@ -0,0 +1,136 @@
+import React, {
+  ElementType,
+  ForwardRefRenderFunction,
+  ReactElement,
+  ReactNode,
+  useEffect,
+  useRef
+} from 'react'
+import { Item, Key, useTabListState } from 'react-stately'
+
+import {
+  createPolymorphicComponent,
+  PolymorphicComponentProps,
+  PolymorphicRef
+} from '../../utils/polymorphic'
+import { TabProps } from './Tab'
+import { TabList } from './TabList'
+import { TabsContext } from './context'
+
+type TabsOwnProps<C extends ElementType> = {
+  /**
+   * A `TabList` (containing `Tab` children) followed by one `TabPanel` per tab.
+   */
+  children?: ReactNode
+  /**
+   * A string of all className you want applied to the base component.
+   */
+  className?: string
+  /**
+   * Component used for the root node. Either a string to use a HTML element or a component.
+   */
+  component?: C
+  /**
+   * The initially selected tab's key (uncontrolled).
+   */
+  defaultSelectedKey?: Key
+  /**
+   * The keys of tabs that cannot be selected, focused, or otherwise interacted with.
+   */
+  disabledKeys?: Iterable<Key>
+  /**
+   * Whether tabs are selected automatically on arrow-key focus (`'automatic'`, the default) or
+   * only on explicit activation — Enter/Space or click (`'manual'`).
+   */
+  keyboardActivation?: 'automatic' | 'manual'
+  /**
+   * Callback fired when the selected tab changes.
+   */
+  onSelectionChange?: (key: Key) => void
+  /**
+   * The orientation of the tab list.
+   */
+  orientation?: 'horizontal' | 'vertical'
+  /**
+   * The selected tab's key (controlled).
+   */
+  selectedKey?: Key
+}
+
+export type TabsProps<C extends ElementType = 'div'> = PolymorphicComponentProps<C, TabsOwnProps<C>>
+
+type TabsComponent = (<C extends ElementType = 'div'>(
+  props: TabsProps<C> & { ref?: PolymorphicRef<C> }
+) => ReactElement | null) & { displayName?: string }
+
+function TabsRender<C extends ElementType = 'div'>(
+  {
+    children,
+    className,
+    component,
+    defaultSelectedKey,
+    disabledKeys,
+    keyboardActivation,
+    onSelectionChange,
+    orientation,
+    selectedKey,
+    ...rest
+  }: TabsProps<C>,
+  ref: PolymorphicRef<C>
+) {
+  const Component = component ?? 'div'
+  // `TabList`'s own children (the `Tab`s) are the source of truth for the collection —
+  // `TabList` never renders them directly (see its own comment), it only reads them here,
+  // at the point react-stately actually needs a collection to build `state` from. This keeps
+  // the public authoring shape as plain composed JSX (matching every other chassis-react
+  // component) instead of exposing react-aria's raw `items`/`Item` collection API directly.
+  const childArray = React.Children.toArray(children)
+  const tabListChild = childArray.find(
+    (child): child is ReactElement<{ children?: ReactNode }> =>
+      React.isValidElement(child) && child.type === TabList
+  )
+  const panelChildren = childArray.filter((child) => child !== tabListChild)
+  const tabs = (tabListChild ? React.Children.toArray(tabListChild.props.children) : []).filter(
+    (child): child is ReactElement<TabProps> => React.isValidElement(child)
+  )
+
+  const tabDisabledKeys = tabs.filter((tab) => tab.props.disabled).map((tab) => tab.props.id)
+  const allDisabledKeys = disabledKeys ? [...disabledKeys, ...tabDisabledKeys] : tabDisabledKeys
+
+  const state = useTabListState<ReactElement<TabProps>>({
+    children: (tab) => (
+      <Item
+        key={tab.props.id}
+        textValue={typeof tab.props.children === 'string' ? tab.props.children : undefined}
+      >
+        {tab.props.children}
+      </Item>
+    ),
+    items: tabs,
+    defaultSelectedKey,
+    disabledKeys: allDisabledKeys,
+    selectedKey,
+    onSelectionChange
+  })
+
+  // Flipped to `false` once the initial commit has painted, so `TabPanel` can tell "selected on
+  // load" apart from "selected by switching" and only fade in the latter.
+  const isInitialSelectionRef = useRef(true)
+  useEffect(() => {
+    isInitialSelectionRef.current = false
+  }, [])
+
+  return (
+    <TabsContext.Provider value={{ keyboardActivation, orientation, state, isInitialSelectionRef }}>
+      <Component className={className} {...rest} ref={ref}>
+        {tabListChild}
+        <div className="tab-content">{panelChildren}</div>
+      </Component>
+    </TabsContext.Provider>
+  )
+}
+
+export const Tabs = createPolymorphicComponent<TabsComponent>(
+  TabsRender as ForwardRefRenderFunction<Element, TabsProps<ElementType>>,
+  'Tabs'
+)

package/src/components/tabs/context.ts

@@ -0,0 +1,24 @@
+import { createContext, MutableRefObject, ReactElement, useContext } from 'react'
+import { TabListState } from 'react-stately'
+
+import { TabProps } from './Tab'
+
+export interface TabsContextValue {
+  keyboardActivation?: 'automatic' | 'manual'
+  orientation?: 'horizontal' | 'vertical'
+  state: TabListState<ReactElement<TabProps>>
+  // Read by `TabPanel` at mount time to skip its fade-in for whichever panel is selected on the
+  // very first render — only a tab *switch* should animate, not the page settling in. `Tabs`
+  // flips this to `false` in an effect once the initial commit has painted.
+  isInitialSelectionRef: MutableRefObject<boolean>
+}
+
+export const TabsContext = createContext<TabsContextValue | null>(null)
+
+export const useTabsContext = (): TabsContextValue => {
+  const context = useContext(TabsContext)
+  if (!context) {
+    throw new Error('TabList and TabPanel must be rendered inside a Tabs')
+  }
+  return context
+}

package/src/components/tabs/index.ts

@@ -0,0 +1,8 @@
+export { Tabs } from './Tabs'
+export type { TabsProps } from './Tabs'
+export { Tab } from './Tab'
+export type { TabProps } from './Tab'
+export { TabList } from './TabList'
+export type { TabListProps } from './TabList'
+export { TabPanel } from './TabPanel'
+export type { TabPanelProps } from './TabPanel'

package/src/components/text-input/TextInput.tsx

@@ -0,0 +1,188 @@
+import React, { forwardRef, InputHTMLAttributes, ReactNode, useRef } from 'react'
+import classNames from 'classnames'
+import { AriaTextFieldProps, useTextField } from 'react-aria'
+
+import { useForkedRef, useFormField } from '../../hooks'
+import { validationClassName } from '../../utils/validationClassName'
+import { renderFormField } from '../form-field/renderFormField'
+
+export interface TextInputProps extends Omit<
+  InputHTMLAttributes<HTMLInputElement>,
+  'defaultValue' | 'onChange' | 'size' | 'value'
+> {
+  /**
+   * Content rendered at the input's trailing edge, e.g. a `InputAdorn` icon, text, or button.
+   * Setting either `adornStart` or `adornEnd` renders a `.form-input` wrapper around a
+   * `.ghost-input`, matching chassis-css's [input help](https://chassis-ui.com/css/docs/forms/input-adorn) pattern.
+   */
+  adornEnd?: ReactNode
+  /**
+   * Content rendered at the input's leading edge, e.g. a `InputAdorn` icon, text, or button.
+   * Setting either `adornStart` or `adornEnd` renders a `.form-input` wrapper around a
+   * `.ghost-input`, matching chassis-css's [input help](https://chassis-ui.com/css/docs/forms/input-adorn) pattern.
+   */
+  adornStart?: ReactNode
+  /**
+   * A string of all className you want applied to the component.
+   */
+  className?: string
+  /**
+   * The value of the input, uncontrolled.
+   */
+  defaultValue?: string
+  /**
+   * Toggle the disabled state for the component.
+   */
+  disabled?: boolean
+  /**
+   * A description for the field, rendered below the input.
+   */
+  help?: ReactNode
+  /**
+   * Set component validation state to invalid.
+   */
+  invalid?: boolean
+  /**
+   * An error message for the field, rendered below the input when `invalid` is set.
+   */
+  invalidFeedback?: ReactNode
+  /**
+   * The field's caption, rendered as a `FormLabel` associated with this input.
+   */
+  label?: ReactNode
+  /**
+   * Handler that is called when the value changes.
+   */
+  onChange?: (value: string) => void
+  /**
+   * Render the component styled as plain text. Removes the default form field styling and preserve the correct margin and padding. Recommend to use only along side `readonly` [docs]
+   */
+  plainText?: boolean
+  /**
+   * Toggle the readonly state for the component.
+   */
+  readOnly?: boolean
+  /**
+   * Size the component small or large.
+   */
+  size?: 'small' | 'large'
+  /**
+   * Specifies the type of component. For `color` or `file` inputs, use the dedicated `ColorInput` or `FileInput` components instead.
+   */
+  type?:
+    | 'date'
+    | 'datetime-local'
+    | 'email'
+    | 'month'
+    | 'password'
+    | 'search'
+    | 'tel'
+    | 'text'
+    | 'time'
+    | 'url'
+    | 'week'
+    | (string & {})
+  /**
+   * Set component validation state to valid.
+   */
+  valid?: boolean
+  /**
+   * A success message for the field, rendered below the input when `valid` is set.
+   */
+  validFeedback?: ReactNode
+  /**
+   * The value of the input, controlled.
+   */
+  value?: string
+}
+
+export const TextInput = forwardRef<HTMLInputElement, TextInputProps>(
+  (
+    {
+      adornEnd,
+      adornStart,
+      className,
+      disabled,
+      help,
+      id,
+      invalid,
+      invalidFeedback,
+      label,
+      plainText,
+      readOnly,
+      size,
+      type = 'text',
+      valid,
+      validFeedback,
+      ...rest
+    },
+    ref
+  ) => {
+    const inputRef = useRef<HTMLInputElement>(null)
+    const forkedRef = useForkedRef(ref, inputRef)
+
+    const { describedBy, feedbackId, helpId, inputId, labelId, labelledBy } = useFormField({
+      ariaDescribedBy: rest['aria-describedby'],
+      ariaLabelledBy: rest['aria-labelledby'],
+      help,
+      id,
+      invalid,
+      invalidFeedback,
+      label,
+      valid,
+      validFeedback
+    })
+
+    const { inputProps } = useTextField(
+      {
+        ...rest,
+        'aria-describedby': describedBy,
+        'aria-labelledby': labelledBy,
+        id: inputId,
+        isDisabled: disabled,
+        isInvalid: invalid,
+        isReadOnly: readOnly,
+        type
+      } as AriaTextFieldProps,
+      inputRef
+    )
+
+    const hasAdorn = adornStart != null || adornEnd != null
+
+    // chassis-css's `.form-input:has(.ghost-input.is-valid)` selector reads validation state off
+    // the inner input, not the wrapper, once adorns turn `.form-input` into a flex container - see
+    // https://chassis-ui.com/css/docs/forms/input-adorn.
+    const inputClassName = classNames(
+      hasAdorn ? 'ghost-input' : 'form-input',
+      !hasAdorn && plainText && 'plaintext',
+      !hasAdorn && size,
+      validationClassName(invalid, valid),
+      !hasAdorn && className
+    )
+
+    const input = <input {...inputProps} className={inputClassName} ref={forkedRef} />
+
+    const children = hasAdorn ? (
+      <div className={classNames('form-input', plainText && 'plaintext', size, className)}>
+        {adornStart}
+        {input}
+        {adornEnd}
+      </div>
+    ) : (
+      input
+    )
+
+    return renderFormField({
+      children,
+      help,
+      ids: { feedback: feedbackId, help: helpId, input: inputId, label: labelId },
+      invalid,
+      invalidFeedback,
+      label,
+      valid,
+      validFeedback
+    })
+  }
+)
+
+TextInput.displayName = 'TextInput'

package/src/components/text-input/index.ts

@@ -0,0 +1,2 @@
+export { TextInput } from './TextInput'
+export type { TextInputProps } from './TextInput'