@proteos/ui 0.31.0

package/src/components/record-filter/types.ts

@@ -0,0 +1,150 @@
+import type { AttributeType } from '../attribute-type-icon'
+import type { BadgeVariants } from '../badge/badge'
+
+/* =========================================================================
+   RecordFilter — types
+
+   The lib speaks a normalized "field schema" dialect (`FilterField[]`) and
+   a canonical filter state (`FilterGroup`). Consumers are responsible for
+   mapping their domain entity into `FilterField[]` (e.g. flattening nested
+   objects, projecting enum options) and for serializing `FilterGroup` to
+   their backend's query format. The lib never touches the SDK or the
+   record-service URL convention directly.
+   ========================================================================= */
+
+/* `FilterFieldType` is the subset of the lib-wide `AttributeType` that can
+   sit on a leaf filter row. `'object'` is excluded because objects are
+   opaque containers — consumers flatten them into dot-paths
+   (`'address.street'`) before handing them to the filter, so an object type
+   never appears here. Deriving from `AttributeType` keeps the icon mapping
+   and the filter type catalogue in lockstep. */
+export type FilterFieldType = Exclude<AttributeType, 'object'>
+
+export type FilterFieldOption = {
+  value: string
+  label: string
+  /** Badge color register, used when this option is rendered as a pill. */
+  variant?: BadgeVariants['variant']
+}
+
+export type FilterField = {
+  /** Dot-path to the attribute, e.g. `'owner.email'`. Stable identifier. */
+  path: string
+  /** Full nested label, e.g. `'Owner / Email'`. Used in pickers. */
+  label: string
+  /** Leaf label only, e.g. `'Email'`. Used in chips. */
+  shortLabel: string
+  /** Parent label for breadcrumb in chips, e.g. `'Owner'`. Omitted for top-level. */
+  parentLabel?: string
+  type: FilterFieldType
+  /** Required when `type === 'enum'`; ignored otherwise. */
+  options?: ReadonlyArray<FilterFieldOption>
+  /** Hint for `<Input type=…>`. Defaults derived from `type`. */
+  inputType?: 'text' | 'number' | 'date' | 'datetime' | 'email'
+  /**
+   * Relationship metadata for fields that traverse a foreign key into a
+   * related entity. Consumers that auto-emit JOINs (e.g. the report
+   * builder) read this to determine how to join the related table; the
+   * core record-filter UI just renders these like any other field.
+   *
+   * Path convention: `<attribute>.<relatedFieldPath>`, e.g.
+   * `'createdBy.firstName'` or `'accountId.address.city'`. The local FK
+   * attribute name is the prefix (not the related entity slug) so multiple
+   * relationships to the same target stay distinguishable.
+   */
+  relation?: FilterFieldRelation
+  /**
+   * LUM-34: pointer to the page-layout control that drives editor + chip
+   * rendering. When set, the consumer's `renderValueInput` dispatches via
+   * the control registry (`registry[controlSlug].Filter`) instead of the
+   * lib's built-in type-switch. The lib treats this as opaque metadata —
+   * it never touches the registry itself.
+   */
+  controlSlug?: string
+  /**
+   * LUM-34: the raw SDK `Attribute` for this field, threaded through to
+   * the descriptor's `Filter` / `Display` components which need full
+   * type+meta context (enum values, relation target, etc.). Typed
+   * `unknown` because the lib has no `@proteos/sdk` dependency;
+   * consumers cast back to `Attribute` in their renderer.
+   */
+  attribute?: unknown
+  /**
+   * LUM-34: per-field operator allowlist. When set, the operator picker
+   * uses this list verbatim instead of the per-type default in
+   * `operatorsForType(type)`. Lets the registry's per-control overrides
+   * (e.g. `password` → `[]`) flow through to the picker without coupling
+   * the lib to the registry.
+   */
+  filterOperators?: ReadonlyArray<ComparisonOperator>
+}
+
+export type FilterFieldRelation = {
+  /** Local FK attribute on this entity, e.g. `'accountId'`. Used as JOIN alias. */
+  attribute: string
+  /** Slug of the related entity table, e.g. `'account'`. */
+  relatedEntitySlug: string
+  /** Attribute on the related entity to join against, typically `'id'`. */
+  relatedAttribute: string
+  /** Dot-path of the field on the related entity, e.g. `'name'` or `'address.city'`. */
+  relatedFieldPath: string
+}
+
+/* =========================================================================
+   Filter state — mirrors `@proteos/sdk`'s FilterGroup/FilterElement so app
+   and lib share one canonical shape. Re-declared locally so the lib has no
+   SDK dependency; callers can `as` between them since the structures match.
+   ========================================================================= */
+
+export type ComparisonOperator =
+  | 'eq'
+  | 'gt'
+  | 'lt'
+  | 'gte'
+  | 'lte'
+  | 'ne'
+  | 'in'
+  | 'not_in'
+  | 'contains'
+  | 'starts_with'
+  | 'ends_with'
+  | 'empty'
+  | 'not_empty'
+
+export type LogicalOperator = 'and' | 'or'
+
+export type FilterValue = string | string[] | boolean | null
+
+export type FilterElement = {
+  field: string
+  operator: ComparisonOperator
+  /**
+   * In-memory value shape. Richer than the SDK's `string`-only `value`
+   * because the UI needs structured arrays for `in`/`not_in` and booleans
+   * for boolean filters. App-level serializers collapse this back to the
+   * SDK's wire format (pipe-joined strings, etc.) at the boundary.
+   */
+  value: FilterValue
+}
+
+export type FilterGroup = {
+  logicalOperator: LogicalOperator
+  elements?: FilterElement[]
+  groups?: FilterGroup[]
+}
+
+/* =========================================================================
+   Operator descriptor — one row of the catalogue.
+   ========================================================================= */
+
+export type OperatorArity = 0 | 1 | 'n'
+
+export type OperatorDescriptor = {
+  id: ComparisonOperator
+  /** Human label shown in the operator picker. */
+  label: string
+  /** Number of values the operator takes. */
+  arity: OperatorArity
+  /** Field types this operator applies to. */
+  types: ReadonlyArray<FilterFieldType>
+}

package/src/components/segmented-control/index.ts

@@ -0,0 +1,6 @@
+export type {
+  SegmentedControlOption,
+  SegmentedControlProps,
+  SegmentedControlVariants,
+} from './segmented-control'
+export { SegmentedControl, segmentedControlStyles } from './segmented-control'

package/src/components/segmented-control/segmented-control.stories.tsx

@@ -0,0 +1,67 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { useState } from 'react'
+
+import { SegmentedControl } from './segmented-control'
+
+const meta: Meta<typeof SegmentedControl> = {
+  title: 'Components/SegmentedControl',
+  component: SegmentedControl,
+  tags: ['autodocs'],
+}
+
+export default meta
+type Story = StoryObj<typeof SegmentedControl>
+
+export const AndOrJoiner: Story = {
+  render: () => {
+    const [value, setValue] = useState<'and' | 'or'>('and')
+    return (
+      <SegmentedControl
+        aria-label="Joiner"
+        options={[
+          { id: 'and', label: 'AND' },
+          { id: 'or', label: 'OR' },
+        ]}
+        value={value}
+        onChange={setValue}
+      />
+    )
+  },
+}
+
+export const BooleanTrueFalse: Story = {
+  render: () => {
+    const [value, setValue] = useState<'true' | 'false'>('true')
+    return (
+      <SegmentedControl
+        size="md"
+        aria-label="Boolean"
+        options={[
+          { id: 'true', label: 'true' },
+          { id: 'false', label: 'false' },
+        ]}
+        value={value}
+        onChange={setValue}
+      />
+    )
+  },
+}
+
+export const ThreeSegments: Story = {
+  render: () => {
+    const [value, setValue] = useState<'compact' | 'cozy' | 'comfy'>('cozy')
+    return (
+      <SegmentedControl
+        size="md"
+        aria-label="Density"
+        options={[
+          { id: 'compact', label: 'Compact' },
+          { id: 'cozy', label: 'Cozy' },
+          { id: 'comfy', label: 'Comfy' },
+        ]}
+        value={value}
+        onChange={setValue}
+      />
+    )
+  },
+}

package/src/components/segmented-control/segmented-control.test.tsx

@@ -0,0 +1,47 @@
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { useState } from 'react'
+import { describe, expect, it, vi } from 'vitest'
+
+import { SegmentedControl } from './segmented-control'
+
+function Harness({ onChange }: { onChange?: (v: 'and' | 'or') => void }) {
+  const [value, setValue] = useState<'and' | 'or'>('and')
+  return (
+    <SegmentedControl
+      aria-label="Joiner"
+      options={[
+        { id: 'and', label: 'AND' },
+        { id: 'or', label: 'OR' },
+      ]}
+      value={value}
+      onChange={(next) => {
+        setValue(next)
+        onChange?.(next)
+      }}
+    />
+  )
+}
+
+describe('SegmentedControl', () => {
+  it('renders options as a radiogroup', () => {
+    render(<Harness />)
+    expect(screen.getByRole('radiogroup', { name: 'Joiner' })).toBeInTheDocument()
+    expect(screen.getAllByRole('radio')).toHaveLength(2)
+  })
+
+  it('reflects the controlled value', () => {
+    render(<Harness />)
+    expect(screen.getByRole('radio', { name: 'AND' })).toBeChecked()
+    expect(screen.getByRole('radio', { name: 'OR' })).not.toBeChecked()
+  })
+
+  it('changes value on click', async () => {
+    const user = userEvent.setup()
+    const onChange = vi.fn()
+    render(<Harness onChange={onChange} />)
+    await user.click(screen.getByRole('radio', { name: 'OR' }))
+    expect(onChange).toHaveBeenLastCalledWith('or')
+    expect(screen.getByRole('radio', { name: 'OR' })).toBeChecked()
+  })
+})

package/src/components/segmented-control/segmented-control.tsx

@@ -0,0 +1,105 @@
+import type { Key, ReactNode } from 'react'
+import {
+  Radio as AriaRadio,
+  RadioGroup as AriaRadioGroup,
+  type RadioGroupProps as AriaRadioGroupProps,
+} from 'react-aria-components'
+import { tv, type VariantProps } from 'tailwind-variants'
+
+import { cn } from '../../lib/cn'
+
+/* =========================================================================
+   SegmentedControl — small horizontal exclusive-choice group with pill
+   chrome. Wraps RAC RadioGroup so keyboard nav and focus management are
+   correct (arrow keys move between segments). Used for compact toggles
+   like AND/OR joiners and true/false booleans where a full RadioGroup
+   feels heavy.
+   ========================================================================= */
+
+export const segmentedControlStyles = tv({
+  slots: {
+    // `w-fit` keeps the group content-width even as a flex/grid item under a
+    // stretching parent (e.g. a `flex flex-col` card body, whose default
+    // align-items:stretch would otherwise pull it to full width). Consumers
+    // can still opt into full width by passing `w-full` via className.
+    group: 'inline-flex w-fit rounded-sm border border-rule-strong bg-surface p-0.5 gap-0.5',
+    segment: [
+      'inline-flex items-center justify-center cursor-pointer',
+      'font-mono tracking-[0.04em] rounded-[3px] outline-none select-none',
+      'transition-[background-color,color] duration-150',
+      'data-[hovered]:text-ink',
+      'data-[selected]:bg-ink data-[selected]:text-surface',
+      'data-[focus-visible]:shadow-[var(--shadow-focus)]',
+      'data-[disabled]:opacity-45 data-[disabled]:cursor-not-allowed',
+    ],
+  },
+  variants: {
+    size: {
+      sm: { segment: 'px-2 py-0.5 text-[10.5px] tracking-[0.08em]' },
+      md: { segment: 'px-2.5 py-1 text-[12px]' },
+    },
+    tone: {
+      // Default: ink fill on selected.
+      default: { segment: 'text-ink-3' },
+    },
+  },
+  defaultVariants: { size: 'sm', tone: 'default' },
+})
+
+export type SegmentedControlVariants = VariantProps<typeof segmentedControlStyles>
+
+export type SegmentedControlOption<T extends Key = Key> = {
+  id: T
+  label: ReactNode
+  isDisabled?: boolean
+}
+
+export type SegmentedControlProps<T extends Key = Key> = Omit<
+  AriaRadioGroupProps,
+  'children' | 'value' | 'onChange'
+> & {
+  options: ReadonlyArray<SegmentedControlOption<T>>
+  value: T
+  onChange: (value: T) => void
+  size?: SegmentedControlVariants['size']
+  /** Focus the selected segment on mount. RAC's RadioGroup doesn't surface
+   *  `autoFocus` itself — it's a per-Radio prop — so we apply it to the
+   *  Radio whose value matches `value`. */
+  autoFocus?: boolean
+  /** Visual override for the group wrapper. */
+  className?: string
+}
+
+export function SegmentedControl<T extends Key>({
+  options,
+  value,
+  onChange,
+  size,
+  autoFocus = false,
+  className,
+  orientation = 'horizontal',
+  ...props
+}: SegmentedControlProps<T>) {
+  const styles = segmentedControlStyles({ size })
+  return (
+    <AriaRadioGroup
+      {...props}
+      orientation={orientation}
+      value={String(value)}
+      onChange={(next) => onChange(next as T)}
+      className={cn(styles.group(), className)}
+    >
+      {options.map((option) => (
+        <AriaRadio
+          key={String(option.id)}
+          value={String(option.id)}
+          {...(option.isDisabled ? { isDisabled: true } : {})}
+          {...(autoFocus && option.id === value ? { autoFocus: true } : {})}
+          className={styles.segment()}
+        >
+          {option.label}
+        </AriaRadio>
+      ))}
+    </AriaRadioGroup>
+  )
+}

package/src/components/select/index.ts

@@ -0,0 +1,2 @@
+export type { SelectOption, SelectProps } from './select'
+export { Select } from './select'

package/src/components/select/select.stories.tsx

@@ -0,0 +1,76 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+
+import { Select } from './select'
+
+const industries = [
+  { id: 'freight', label: 'Freight & logistics' },
+  { id: 'lending', label: 'Specialty lending' },
+  { id: 'clinical', label: 'Clinical trials' },
+  { id: 'services', label: 'Professional services' },
+  { id: 'insurance', label: 'Insurance MGA' },
+  { id: 'b2b', label: 'B2B SaaS' },
+]
+
+const meta: Meta<typeof Select> = {
+  title: 'Components/Select',
+  component: Select,
+  tags: ['autodocs'],
+  args: {
+    label: 'Industry',
+    placeholder: 'Pick an industry',
+    options: industries,
+  },
+  argTypes: {
+    isDisabled: { control: { type: 'boolean' } },
+    isInvalid: { control: { type: 'boolean' } },
+  },
+  decorators: [
+    (Story) => (
+      <div className="w-[440px]">
+        <Story />
+      </div>
+    ),
+  ],
+}
+
+export default meta
+type Story = StoryObj<typeof Select>
+
+export const Playground: Story = {}
+
+export const WithDescription: Story = {
+  args: {
+    description: 'Proteos pre-seeds the entity model from this.',
+  },
+}
+
+export const Invalid: Story = {
+  args: {
+    isInvalid: true,
+    errorMessage: 'Select an industry to continue.',
+  },
+}
+
+export const Disabled: Story = {
+  args: {
+    defaultSelectedKey: 'freight',
+    isDisabled: true,
+  },
+}
+
+export const AllStates: Story = {
+  parameters: { controls: { hideNoControlsWarning: true } },
+  render: () => (
+    <div className="grid gap-5 w-[440px]">
+      <Select label="Rest" options={industries} />
+      <Select label="Selected" options={industries} defaultSelectedKey="lending" />
+      <Select
+        label="Invalid"
+        options={industries}
+        isInvalid
+        errorMessage="Select an industry to continue."
+      />
+      <Select label="Disabled" options={industries} defaultSelectedKey="clinical" isDisabled />
+    </div>
+  ),
+}

package/src/components/select/select.test.tsx

@@ -0,0 +1,56 @@
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { describe, expect, it, vi } from 'vitest'
+
+import { Select } from './select'
+
+const industries = [
+  { id: 'freight', label: 'Freight & logistics' },
+  { id: 'lending', label: 'Specialty lending' },
+  { id: 'clinical', label: 'Clinical trials' },
+] as const
+
+describe('Select', () => {
+  it('renders a labelled select trigger', () => {
+    render(<Select label="Industry" options={[...industries]} />)
+    expect(screen.getByRole('button', { name: /industry/i })).toBeInTheDocument()
+  })
+
+  it('opens the listbox on click and selects an option', async () => {
+    const user = userEvent.setup()
+    const onSelectionChange = vi.fn()
+    render(
+      <Select label="Industry" options={[...industries]} onSelectionChange={onSelectionChange} />,
+    )
+
+    await user.click(screen.getByRole('button', { name: /industry/i }))
+    const listbox = await screen.findByRole('listbox')
+    expect(listbox).toBeInTheDocument()
+
+    await user.click(screen.getByRole('option', { name: 'Specialty lending' }))
+    expect(onSelectionChange).toHaveBeenCalledWith('lending')
+  })
+
+  it('supports keyboard navigation', async () => {
+    const user = userEvent.setup()
+    render(<Select label="Industry" options={[...industries]} />)
+
+    await user.tab()
+    expect(screen.getByRole('button', { name: /industry/i })).toHaveFocus()
+
+    await user.keyboard('{Enter}')
+    expect(await screen.findByRole('listbox')).toBeInTheDocument()
+  })
+
+  it('shows placeholder when nothing is selected', () => {
+    render(<Select label="Industry" placeholder="Pick one" options={[...industries]} />)
+    const trigger = screen.getByRole('button', { name: /industry/i })
+    expect(trigger).toHaveTextContent('Pick one')
+  })
+
+  it('renders a controlled selection', () => {
+    render(<Select label="Industry" options={[...industries]} selectedKey="clinical" />)
+    const trigger = screen.getByRole('button', { name: /industry/i })
+    expect(trigger).toHaveTextContent('Clinical trials')
+  })
+})

package/src/components/select/select.tsx

@@ -0,0 +1,159 @@
+import type { ReactNode } from 'react'
+import {
+  Select as AriaSelect,
+  Button as AriaSelectButton,
+  type SelectProps as AriaSelectProps,
+  FieldError,
+  type Key,
+  Label,
+  ListBox,
+  ListBoxItem,
+  type ListBoxItemProps,
+  Popover,
+  SelectValue,
+  Text,
+} from 'react-aria-components'
+import { cn } from '../../lib/cn'
+import {
+  type FieldAppearance,
+  FieldCaret,
+  type FieldSize,
+  fieldControlStyles,
+  fieldErrorStyles,
+  fieldHintStyles,
+  fieldLabelStyles,
+} from '../field/field'
+
+export type SelectOption<T extends Key = Key> = {
+  id: T
+  label: ReactNode
+  /** Plain-text stand-in for typeahead/accessibility when `label` is a
+   *  ReactNode. Optional for string labels (RAC derives the text itself). */
+  textValue?: string
+  description?: ReactNode
+  isDisabled?: boolean
+}
+
+export type SelectProps<T extends Key = Key> = Omit<AriaSelectProps<never>, 'children'> & {
+  label?: ReactNode
+  description?: ReactNode
+  errorMessage?: ReactNode
+  placeholder?: string
+  options: ReadonlyArray<SelectOption<T>>
+  /** Optional custom renderer for a ListBoxItem. */
+  renderItem?: (option: SelectOption<T>) => ReactNode
+  /** Field size. Defaults to `md`. */
+  size?: FieldSize
+  /** Chrome variant. Defaults to `field`. `cell` flattens the trigger box. */
+  appearance?: FieldAppearance
+  /** Visual override for the trigger only. */
+  triggerClassName?: string
+  /** Visual override for the popover — e.g. `min-w-[var(--trigger-width)]
+   *  w-max` to size to content when the trigger is intrinsic-width. Defaults
+   *  to matching the trigger width exactly. */
+  popoverClassName?: string
+}
+
+export function Select<T extends Key>({
+  label,
+  description,
+  errorMessage,
+  placeholder = 'Select…',
+  options,
+  renderItem,
+  size,
+  appearance,
+  triggerClassName,
+  popoverClassName,
+  className,
+  ...props
+}: SelectProps<T>) {
+  const styles = fieldControlStyles({ size, appearance })
+  return (
+    <AriaSelect
+      {...props}
+      className={(renderProps) =>
+        cn(
+          'grid grid-cols-1 gap-1.5',
+          typeof className === 'function' ? className(renderProps) : className,
+        )
+      }
+    >
+      {label ? <Label className={fieldLabelStyles}>{label}</Label> : null}
+      <AriaSelectButton
+        className={cn(
+          styles.box(),
+          styles.content(),
+          'flex items-center justify-between gap-3 text-left cursor-pointer',
+          triggerClassName,
+        )}
+      >
+        <SelectValue className="truncate">
+          {({ defaultChildren, isPlaceholder }) =>
+            isPlaceholder ? <span className="text-ink-4">{placeholder}</span> : defaultChildren
+          }
+        </SelectValue>
+        <FieldCaret />
+      </AriaSelectButton>
+
+      {description ? (
+        <Text slot="description" className={fieldHintStyles}>
+          {description}
+        </Text>
+      ) : null}
+      {errorMessage && appearance !== 'cell' ? (
+        <FieldError className={fieldErrorStyles}>{errorMessage}</FieldError>
+      ) : null}
+
+      <Popover
+        offset={6}
+        className={cn(
+          // Match the trigger width exactly (RAC exposes --trigger-width on
+          // the Popover when anchored to a Select button).
+          'w-[var(--trigger-width)]',
+          // Float above modals + full-screen editors (e.g. agent-studio's
+          // .as-editor z-1000 / a raised modal overlay), matching Menu's z-[1200].
+          'z-[1300]',
+          'rounded-md border border-rule bg-surface p-1',
+          'shadow-[var(--shadow-raised)]',
+          'entering:animate-in entering:fade-in-0 entering:slide-in-from-top-1',
+          'exiting:animate-out exiting:fade-out-0 exiting:slide-out-to-top-1',
+          popoverClassName,
+        )}
+      >
+        <ListBox className="outline-none max-h-72 overflow-auto">
+          {options.map((option) => (
+            <SelectItem
+              key={option.id}
+              id={option.id}
+              {...(option.textValue ? { textValue: option.textValue } : {})}
+              {...(option.isDisabled ? { isDisabled: true } : {})}
+            >
+              {renderItem ? renderItem(option) : option.label}
+            </SelectItem>
+          ))}
+        </ListBox>
+        {options.length === 0 ? (
+          <div className={cn('px-3 py-2', fieldHintStyles)}>{placeholder}</div>
+        ) : null}
+      </Popover>
+    </AriaSelect>
+  )
+}
+
+function SelectItem(props: ListBoxItemProps) {
+  return (
+    <ListBoxItem
+      {...props}
+      className={cn(
+        'flex items-center justify-between gap-3',
+        'rounded-[6px] px-3 py-2 text-[14px] text-ink-2',
+        'cursor-pointer outline-none select-none',
+        'data-[hovered]:bg-surface-2 data-[hovered]:text-ink',
+        'data-[focused]:bg-surface-2 data-[focused]:text-ink',
+        'data-[selected]:bg-surface-3 data-[selected]:text-ink',
+        'data-[disabled]:opacity-45 data-[disabled]:cursor-not-allowed',
+      )}
+    />
+  )
+}

package/src/components/separator/index.ts

@@ -0,0 +1,2 @@
+export type { SeparatorProps } from './separator'
+export { Separator } from './separator'