@proteos/ui 0.31.0

package/src/components/avatar/avatar.stories.tsx

@@ -0,0 +1,42 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+
+import { Avatar } from './avatar'
+
+const meta: Meta<typeof Avatar> = {
+  title: 'Components/Avatar',
+  component: Avatar,
+  tags: ['autodocs'],
+  argTypes: {
+    size: { control: 'inline-radio', options: ['sm', 'md', 'lg'] },
+    tone: { control: 'inline-radio', options: ['paper', 'indigo', 'moss', 'terra', 'slate'] },
+  },
+}
+
+export default meta
+type Story = StoryObj<typeof Avatar>
+
+export const Playground: Story = { args: { initials: 'JM' } }
+
+export const Tones: Story = {
+  parameters: { controls: { hideNoControlsWarning: true } },
+  render: () => (
+    <div className="flex items-center gap-3">
+      <Avatar initials="JM" />
+      <Avatar tone="indigo" initials="N" />
+      <Avatar tone="moss" initials="M" />
+      <Avatar tone="terra" initials="A" />
+      <Avatar tone="slate" initials="S" />
+    </div>
+  ),
+}
+
+export const Sizes: Story = {
+  parameters: { controls: { hideNoControlsWarning: true } },
+  render: () => (
+    <div className="flex items-end gap-3">
+      <Avatar size="sm" initials="SM" />
+      <Avatar size="md" initials="MD" />
+      <Avatar size="lg" initials="LG" />
+    </div>
+  ),
+}

package/src/components/avatar/avatar.tsx

@@ -0,0 +1,48 @@
+import type { HTMLAttributes } from 'react'
+import { tv, type VariantProps } from 'tailwind-variants'
+
+import { cn } from '../../lib/cn'
+
+/* =========================================================================
+   Avatar — round, paper-tinted initials chip. Mono glyph, hairline border.
+   For square colored "app tiles" use the AppSwitcher's internal tile —
+   Avatar is reserved for people.
+   ========================================================================= */
+
+export const avatarStyles = tv({
+  base: [
+    'inline-grid place-items-center shrink-0 select-none',
+    'rounded-full border',
+    'font-mono font-medium tracking-[-0.005em]',
+  ],
+  variants: {
+    size: {
+      sm: 'size-[22px] text-[10px]',
+      md: 'size-7 text-[12px]',
+      lg: 'size-9 text-[13px]',
+    },
+    tone: {
+      paper: 'bg-surface-3 text-ink border-rule',
+      indigo: 'bg-accent text-[#f0efe8] border-transparent',
+      moss: 'bg-[#5b7052] text-[#f0efe8] border-transparent',
+      terra: 'bg-[#8a5a3f] text-[#f0efe8] border-transparent',
+      slate: 'bg-ink text-surface border-transparent',
+    },
+  },
+  defaultVariants: { size: 'md', tone: 'paper' },
+})
+
+export type AvatarVariants = VariantProps<typeof avatarStyles>
+export type AvatarProps = HTMLAttributes<HTMLSpanElement> &
+  AvatarVariants & {
+    /** 1–2 character initials. Ignored if `children` is provided. */
+    initials?: string
+  }
+
+export function Avatar({ size, tone, initials, className, children, ...props }: AvatarProps) {
+  return (
+    <span {...props} className={cn(avatarStyles({ size, tone }), className)}>
+      {children ?? initials}
+    </span>
+  )
+}

package/src/components/avatar/index.ts

@@ -0,0 +1,2 @@
+export type { AvatarProps, AvatarVariants } from './avatar'
+export { Avatar, avatarStyles } from './avatar'

package/src/components/avatar-group/avatar-group.test.tsx

@@ -0,0 +1,38 @@
+import { render, screen } from '@testing-library/react'
+import { describe, expect, it } from 'vitest'
+
+import { AvatarGroup } from './avatar-group'
+
+describe('AvatarGroup', () => {
+  it('renders one avatar per person up to max', () => {
+    render(
+      <AvatarGroup
+        avatars={[
+          { initials: 'AB', key: 'a' },
+          { initials: 'CD', key: 'b' },
+        ]}
+      />,
+    )
+    expect(screen.getByText('AB')).toBeInTheDocument()
+    expect(screen.getByText('CD')).toBeInTheDocument()
+    expect(screen.queryByText(/^\+/)).not.toBeInTheDocument()
+  })
+
+  it('collapses the overflow into a +N chip', () => {
+    render(
+      <AvatarGroup
+        max={2}
+        avatars={[
+          { initials: 'AB', key: 'a' },
+          { initials: 'CD', key: 'b' },
+          { initials: 'EF', key: 'c' },
+          { initials: 'GH', key: 'd' },
+        ]}
+      />,
+    )
+    expect(screen.getByText('AB')).toBeInTheDocument()
+    expect(screen.getByText('CD')).toBeInTheDocument()
+    expect(screen.queryByText('EF')).not.toBeInTheDocument()
+    expect(screen.getByText('+2')).toBeInTheDocument()
+  })
+})

package/src/components/avatar-group/avatar-group.tsx

@@ -0,0 +1,60 @@
+import type { HTMLAttributes } from 'react'
+import { tv, type VariantProps } from 'tailwind-variants'
+
+import { cn } from '../../lib/cn'
+import { Avatar, type AvatarVariants } from '../avatar/avatar'
+
+/* =========================================================================
+   AvatarGroup — a stack of overlapping people avatars with a +N overflow
+   chip. Used to render a conversation's roster: one avatar for a 1:1 thread,
+   several overlapping for a group. Each avatar wears a bg-colored ring so the
+   overlap reads as separate chips.
+   ========================================================================= */
+
+export const avatarGroupStyles = tv({
+  base: 'flex items-center',
+  variants: {
+    size: {
+      sm: '-space-x-1.5',
+      md: '-space-x-2',
+      lg: '-space-x-2.5',
+    },
+  },
+  defaultVariants: { size: 'md' },
+})
+
+export type AvatarGroupVariants = VariantProps<typeof avatarGroupStyles>
+
+/** One person in the stack — initials plus an optional tone. */
+export interface AvatarGroupItem {
+  initials: string
+  tone?: AvatarVariants['tone']
+  /** Stable key (e.g. the participant's external id); falls back to the index. */
+  key?: string
+}
+
+export type AvatarGroupProps = Omit<HTMLAttributes<HTMLSpanElement>, 'children'> &
+  AvatarGroupVariants & {
+    avatars: AvatarGroupItem[]
+    /** Max avatars shown before the rest collapse into a +N chip. Default 3. */
+    max?: number
+  }
+
+export function AvatarGroup({ avatars, max = 3, size = 'md', className, ...props }: AvatarGroupProps) {
+  const shown = avatars.slice(0, max)
+  const overflow = avatars.length - shown.length
+  return (
+    <span {...props} className={cn(avatarGroupStyles({ size }), className)}>
+      {shown.map((avatar, index) => (
+        <span key={avatar.key ?? index} className="rounded-full ring-[1.5px] ring-surface">
+          <Avatar size={size} tone={avatar.tone ?? 'paper'} initials={avatar.initials} />
+        </span>
+      ))}
+      {overflow > 0 && (
+        <span className="rounded-full ring-[1.5px] ring-surface">
+          <Avatar size={size} tone="paper" initials={`+${overflow}`} />
+        </span>
+      )}
+    </span>
+  )
+}

package/src/components/avatar-group/index.ts

@@ -0,0 +1,2 @@
+export type { AvatarGroupItem, AvatarGroupProps, AvatarGroupVariants } from './avatar-group'
+export { AvatarGroup, avatarGroupStyles } from './avatar-group'

package/src/components/badge/badge.stories.tsx

@@ -0,0 +1,62 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+
+import { Badge } from './badge'
+
+const meta: Meta<typeof Badge> = {
+  title: 'Components/Badge',
+  component: Badge,
+  tags: ['autodocs'],
+  args: {
+    children: 'in transit',
+    variant: 'active',
+  },
+  argTypes: {
+    variant: {
+      control: { type: 'inline-radio' },
+      options: ['default', 'neutral', 'active', 'success', 'warning', 'danger'],
+    },
+  },
+}
+
+export default meta
+type Story = StoryObj<typeof Badge>
+
+export const Playground: Story = {}
+
+export const AllVariants: Story = {
+  parameters: { controls: { hideNoControlsWarning: true } },
+  render: () => (
+    <div className="flex flex-wrap items-center gap-2">
+      <Badge variant="active">in transit</Badge>
+      <Badge>quoted</Badge>
+      <Badge variant="neutral">dispatching</Badge>
+      <Badge variant="success">reconciled</Badge>
+      <Badge variant="warning">past due</Badge>
+      <Badge variant="danger">exception</Badge>
+    </div>
+  ),
+}
+
+export const InContext: Story = {
+  parameters: { controls: { hideNoControlsWarning: true } },
+  render: () => (
+    <div className="w-[480px] grid gap-3 font-mono text-[12.5px] text-ink-2">
+      <div className="flex items-center justify-between border-b border-dashed border-rule pb-3">
+        <span>SH-10482 · DAL → ATL</span>
+        <Badge variant="active">in transit</Badge>
+      </div>
+      <div className="flex items-center justify-between border-b border-dashed border-rule pb-3">
+        <span>SH-10483 · CHI → MSP</span>
+        <Badge variant="neutral">dispatching</Badge>
+      </div>
+      <div className="flex items-center justify-between border-b border-dashed border-rule pb-3">
+        <span>SH-10486 · MIA → JFK</span>
+        <Badge variant="warning">past due</Badge>
+      </div>
+      <div className="flex items-center justify-between">
+        <span>SH-10487 · SEA → BOI</span>
+        <Badge variant="danger">exception</Badge>
+      </div>
+    </div>
+  ),
+}

package/src/components/badge/badge.test.tsx

@@ -0,0 +1,36 @@
+import { render, screen } from '@testing-library/react'
+import { describe, expect, it } from 'vitest'
+
+import { Badge } from './badge'
+
+describe('Badge', () => {
+  it('renders its content', () => {
+    render(<Badge>in transit</Badge>)
+    expect(screen.getByText('in transit')).toBeInTheDocument()
+  })
+
+  it('applies the default variant classes', () => {
+    render(<Badge>quoted</Badge>)
+    expect(screen.getByText('quoted').className).toContain('text-ink-3')
+  })
+
+  it('applies the active variant classes', () => {
+    render(<Badge variant="active">in transit</Badge>)
+    expect(screen.getByText('in transit').className).toContain('text-accent-ink')
+  })
+
+  it('applies the danger variant classes', () => {
+    render(<Badge variant="danger">exception</Badge>)
+    expect(screen.getByText('exception').className).toContain('text-danger')
+  })
+
+  it('merges custom classes', () => {
+    render(
+      <Badge variant="success" className="ml-3">
+        reconciled
+      </Badge>,
+    )
+    expect(screen.getByText('reconciled').className).toContain('ml-3')
+    expect(screen.getByText('reconciled').className).toContain('text-success')
+  })
+})

package/src/components/badge/badge.tsx

@@ -0,0 +1,54 @@
+import type { HTMLAttributes } from 'react'
+import { tv, type VariantProps } from 'tailwind-variants'
+
+import { cn } from '../../lib/cn'
+
+/* =========================================================================
+   Badge — mono, pill-shaped status chip with a leading dot.
+   Matches the Proteos spec's six registers: default, neutral, active (indigo),
+   success, warning, danger. Paper-compatible fills — never pure-color.
+   ========================================================================= */
+
+export const badgeStyles = tv({
+  base: [
+    'inline-flex items-center gap-1.5',
+    'font-mono text-[11.5px] tracking-[-0.005em]',
+    'px-2.5 py-0.5 rounded-pill border',
+    // Leading dot
+    'before:content-[""] before:block before:size-1.5 before:rounded-full',
+  ],
+  variants: {
+    variant: {
+      default: 'border-rule bg-surface text-ink-3 before:bg-ink-4',
+      neutral: 'border-rule bg-surface-3 text-ink-2 before:bg-ink-3',
+      active: [
+        'text-accent-ink before:bg-accent',
+        'border-[color-mix(in_oklab,var(--color-accent)_35%,var(--color-rule))]',
+        'bg-[color-mix(in_oklab,var(--color-accent)_14%,var(--color-surface))]',
+      ],
+      success: [
+        'text-success before:bg-success',
+        'border-[color-mix(in_oklab,var(--color-success)_35%,var(--color-rule))]',
+        'bg-[color-mix(in_oklab,var(--color-success)_12%,var(--color-surface))]',
+      ],
+      warning: [
+        'text-warning before:bg-warning',
+        'border-[color-mix(in_oklab,var(--color-warning)_35%,var(--color-rule))]',
+        'bg-[color-mix(in_oklab,var(--color-warning)_14%,var(--color-surface))]',
+      ],
+      danger: [
+        'text-danger before:bg-danger',
+        'border-[color-mix(in_oklab,var(--color-danger)_40%,var(--color-rule))]',
+        'bg-[color-mix(in_oklab,var(--color-danger)_12%,var(--color-surface))]',
+      ],
+    },
+  },
+  defaultVariants: { variant: 'default' },
+})
+
+export type BadgeVariants = VariantProps<typeof badgeStyles>
+export type BadgeProps = HTMLAttributes<HTMLSpanElement> & BadgeVariants
+
+export function Badge({ variant, className, ...props }: BadgeProps) {
+  return <span {...props} className={cn(badgeStyles({ variant }), className)} />
+}

package/src/components/badge/index.ts

@@ -0,0 +1,2 @@
+export type { BadgeProps, BadgeVariants } from './badge'
+export { Badge, badgeStyles } from './badge'

package/src/components/badge-multi-select/badge-multi-select.stories.tsx

@@ -0,0 +1,177 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { useState } from 'react'
+
+import { BadgeMultiSelect, type BadgeMultiSelectOption } from './badge-multi-select'
+
+const meta: Meta<typeof BadgeMultiSelect> = {
+  title: 'Components/BadgeMultiSelect',
+  component: BadgeMultiSelect,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <div className="w-[440px]">
+        <Story />
+      </div>
+    ),
+  ],
+}
+
+export default meta
+type Story = StoryObj<typeof BadgeMultiSelect>
+
+const statuses: BadgeMultiSelectOption<string>[] = [
+  { id: 'in-transit', label: 'in transit', variant: 'active' },
+  { id: 'quoted', label: 'quoted' },
+  { id: 'dispatching', label: 'dispatching', variant: 'neutral' },
+  { id: 'reconciled', label: 'reconciled', variant: 'success' },
+  { id: 'past-due', label: 'past due', variant: 'warning' },
+  { id: 'exception', label: 'exception', variant: 'danger' },
+]
+
+export const Playground: Story = {
+  render: () => {
+    const [selected, setSelected] = useState<Set<string>>(new Set(['in-transit', 'past-due']))
+    return (
+      <BadgeMultiSelect
+        label="Statuses to include"
+        placeholder="Any status"
+        description="Filter the shipment board by one or more statuses."
+        options={statuses}
+        selectedKeys={selected}
+        onSelectionChange={setSelected}
+      />
+    )
+  },
+}
+
+export const Empty: Story = {
+  render: () => {
+    const [selected, setSelected] = useState<Set<string>>(new Set())
+    return (
+      <BadgeMultiSelect
+        label="Statuses"
+        placeholder="Any status"
+        options={statuses}
+        selectedKeys={selected}
+        onSelectionChange={setSelected}
+      />
+    )
+  },
+}
+
+/** `hideSelectedOptions` — already-selected items disappear from the
+ *  dropdown. Removal happens only via the chip × in the trigger. Useful
+ *  when the list is long and you want to see what's left to pick. */
+export const HideSelected: Story = {
+  render: () => {
+    const [selected, setSelected] = useState<Set<string>>(new Set(['in-transit']))
+    return (
+      <BadgeMultiSelect
+        label="Statuses"
+        placeholder="Any status"
+        description="Selected statuses are hidden from the menu — remove them via × above."
+        options={statuses}
+        selectedKeys={selected}
+        onSelectionChange={setSelected}
+        hideSelectedOptions
+      />
+    )
+  },
+}
+
+export const ManySelected: Story = {
+  render: () => {
+    const [selected, setSelected] = useState<Set<string>>(
+      new Set(['in-transit', 'quoted', 'reconciled', 'past-due', 'exception']),
+    )
+    return (
+      <BadgeMultiSelect
+        label="Statuses"
+        placeholder="Any status"
+        options={statuses}
+        selectedKeys={selected}
+        onSelectionChange={setSelected}
+      />
+    )
+  },
+}
+
+export const Invalid: Story = {
+  render: () => {
+    const [selected, setSelected] = useState<Set<string>>(new Set())
+    return (
+      <BadgeMultiSelect
+        label="Statuses"
+        placeholder="Any status"
+        options={statuses}
+        selectedKeys={selected}
+        onSelectionChange={setSelected}
+        isInvalid
+        errorMessage="Pick at least one status."
+      />
+    )
+  },
+}
+
+export const Disabled: Story = {
+  render: () => (
+    <BadgeMultiSelect
+      label="Statuses"
+      options={statuses}
+      selectedKeys={new Set(['in-transit', 'past-due'])}
+      onSelectionChange={() => {}}
+      isDisabled
+    />
+  ),
+}
+
+export const AllStates: Story = {
+  parameters: { controls: { hideNoControlsWarning: true } },
+  render: () => {
+    const [a, setA] = useState<Set<string>>(new Set())
+    const [b, setB] = useState<Set<string>>(new Set(['in-transit']))
+    const [c, setC] = useState<Set<string>>(new Set(['in-transit', 'past-due', 'exception']))
+    return (
+      <div className="grid gap-5 w-[440px]">
+        <BadgeMultiSelect
+          label="Empty"
+          placeholder="Any status"
+          options={statuses}
+          selectedKeys={a}
+          onSelectionChange={setA}
+        />
+        <BadgeMultiSelect
+          label="One selection"
+          placeholder="Any status"
+          options={statuses}
+          selectedKeys={b}
+          onSelectionChange={setB}
+        />
+        <BadgeMultiSelect
+          label="Multiple selections"
+          placeholder="Any status"
+          options={statuses}
+          selectedKeys={c}
+          onSelectionChange={setC}
+        />
+        <BadgeMultiSelect
+          label="Invalid"
+          placeholder="Any status"
+          options={statuses}
+          selectedKeys={new Set<string>()}
+          onSelectionChange={() => {}}
+          isInvalid
+          errorMessage="Pick at least one status."
+        />
+        <BadgeMultiSelect
+          label="Disabled"
+          placeholder="Any status"
+          options={statuses}
+          selectedKeys={new Set(['in-transit'])}
+          onSelectionChange={() => {}}
+          isDisabled
+        />
+      </div>
+    )
+  },
+}