@duro-app/ui 0.12.2 → 0.14.0

package/src/components/ToggleGroup/ToggleGroup.tsx

@@ -0,0 +1,63 @@
+import {type ReactNode, useCallback} from 'react'
+import {html} from 'react-strict-dom'
+import {useControllableValue} from '../../hooks/useControllableValue'
+import type {ToggleSize} from '../Toggle/Toggle'
+import {ToggleGroupContext, type Orientation} from './ToggleGroupContext'
+import {styles} from './styles.css'
+
+interface ToggleGroupProps {
+  /** Controlled value — array of pressed item values. */
+  value?: string[]
+  /** Initial value (uncontrolled). */
+  defaultValue?: string[]
+  /** Callback fired when the set of pressed values changes. */
+  onValueChange?: (value: string[]) => void
+  /** When false, at most one item can be pressed at a time. */
+  multiple?: boolean
+  /** Prevents interaction with all items. */
+  disabled?: boolean
+  /** Layout direction. */
+  orientation?: Orientation
+  /** Size applied to all child toggles. */
+  size?: ToggleSize
+  children: ReactNode
+}
+
+export function ToggleGroup({
+  value: controlledValue,
+  defaultValue = [],
+  onValueChange,
+  multiple = false,
+  disabled = false,
+  orientation = 'horizontal',
+  size = 'default',
+  children,
+}: ToggleGroupProps) {
+  const [value, setValue] = useControllableValue(controlledValue, defaultValue, onValueChange)
+
+  const toggle = useCallback(
+    (itemValue: string) => {
+      const nextPressed = !value.includes(itemValue)
+      let next: string[]
+      if (multiple) {
+        next = nextPressed ? [...value, itemValue] : value.filter((v) => v !== itemValue)
+      } else {
+        next = nextPressed ? [itemValue] : []
+      }
+      setValue(next)
+    },
+    [value, multiple, setValue],
+  )
+
+  return (
+    <ToggleGroupContext.Provider value={{value, toggle, disabled, orientation, size}}>
+      <html.div
+        role="group"
+        aria-orientation={orientation}
+        style={[styles.root, orientation === 'vertical' && styles.vertical]}
+      >
+        {children}
+      </html.div>
+    </ToggleGroupContext.Provider>
+  )
+}

package/src/components/ToggleGroup/ToggleGroupContext.ts

@@ -0,0 +1,18 @@
+import {createContext, useContext} from 'react'
+import type {ToggleSize} from '../Toggle/Toggle'
+
+export type Orientation = 'horizontal' | 'vertical'
+
+export interface ToggleGroupContextValue {
+  value: string[]
+  toggle: (itemValue: string) => void
+  disabled: boolean
+  orientation: Orientation
+  size: ToggleSize
+}
+
+export const ToggleGroupContext = createContext<ToggleGroupContextValue | null>(null)
+
+export function useToggleGroup() {
+  return useContext(ToggleGroupContext)
+}

package/src/components/ToggleGroup/styles.css.ts

@@ -0,0 +1,17 @@
+import {css} from 'react-strict-dom'
+import {colors} from '@duro-app/tokens/tokens/colors.css'
+import {radii} from '@duro-app/tokens/tokens/spacing.css'
+
+export const styles = css.create({
+  root: {
+    display: 'inline-flex',
+    borderRadius: radii.sm,
+    borderWidth: 1,
+    borderStyle: 'solid',
+    borderColor: colors.border,
+    overflow: 'hidden',
+  },
+  vertical: {
+    flexDirection: 'column',
+  },
+})

package/src/components/Tooltip/Tooltip.stories.tsx

@@ -0,0 +1,127 @@
+import type {Meta, StoryObj} from '@storybook/react'
+import {expect} from 'storybook/test'
+import {css, html} from 'react-strict-dom'
+import {Tooltip} from './Tooltip'
+import {Badge} from '../Badge/Badge'
+
+const meta: Meta = {
+  title: 'Components/Tooltip',
+}
+
+export default meta
+type Story = StoryObj
+
+const centerStyles = css.create({
+  center: {
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    padding: 80,
+    gap: 24,
+  },
+})
+
+export const Default: Story = {
+  render: () => (
+    <html.div style={centerStyles.center}>
+      <Tooltip.Root content="This is a tooltip" delay={0}>
+        <Tooltip.Trigger>
+          <html.span>Hover me</html.span>
+        </Tooltip.Trigger>
+      </Tooltip.Root>
+    </html.div>
+  ),
+  play: async ({canvas, userEvent}) => {
+    const trigger = canvas.getByText('Hover me')
+
+    // Tooltip not visible initially
+    await expect(canvas.queryByRole('tooltip')).not.toBeInTheDocument()
+
+    // Hover to show
+    await userEvent.hover(trigger)
+    const tooltip = canvas.getByRole('tooltip')
+    await expect(tooltip).toBeInTheDocument()
+    await expect(tooltip).toHaveTextContent('This is a tooltip')
+
+    // Unhover to hide
+    await userEvent.unhover(trigger)
+    await expect(canvas.queryByRole('tooltip')).not.toBeInTheDocument()
+  },
+}
+
+export const Placements: Story = {
+  render: () => (
+    <html.div style={centerStyles.center}>
+      <Tooltip.Root content="Top tooltip" placement="top">
+        <Tooltip.Trigger>
+          <Badge>Top</Badge>
+        </Tooltip.Trigger>
+      </Tooltip.Root>
+      <Tooltip.Root content="Bottom tooltip" placement="bottom">
+        <Tooltip.Trigger>
+          <Badge>Bottom</Badge>
+        </Tooltip.Trigger>
+      </Tooltip.Root>
+      <Tooltip.Root content="Left tooltip" placement="left">
+        <Tooltip.Trigger>
+          <Badge>Left</Badge>
+        </Tooltip.Trigger>
+      </Tooltip.Root>
+      <Tooltip.Root content="Right tooltip" placement="right">
+        <Tooltip.Trigger>
+          <Badge>Right</Badge>
+        </Tooltip.Trigger>
+      </Tooltip.Root>
+    </html.div>
+  ),
+}
+
+export const WithBadge: Story = {
+  render: () => (
+    <html.div style={centerStyles.center}>
+      <Tooltip.Root content="Security score: A+" delay={0}>
+        <Tooltip.Trigger>
+          <Badge variant="success">Secure</Badge>
+        </Tooltip.Trigger>
+      </Tooltip.Root>
+      <Tooltip.Root content="Certificate expires in 3 days" delay={0}>
+        <Tooltip.Trigger>
+          <Badge variant="warning">Expiring</Badge>
+        </Tooltip.Trigger>
+      </Tooltip.Root>
+      <Tooltip.Root content="Certificate has expired" delay={0}>
+        <Tooltip.Trigger>
+          <Badge variant="error">Expired</Badge>
+        </Tooltip.Trigger>
+      </Tooltip.Root>
+    </html.div>
+  ),
+  play: async ({canvas, userEvent}) => {
+    // Hover first badge
+    await userEvent.hover(canvas.getByText('Secure'))
+    await expect(canvas.getByRole('tooltip')).toHaveTextContent('Security score: A+')
+    await userEvent.unhover(canvas.getByText('Secure'))
+
+    // Hover second badge
+    await userEvent.hover(canvas.getByText('Expiring'))
+    await expect(canvas.getByRole('tooltip')).toHaveTextContent('Certificate expires in 3 days')
+    await userEvent.unhover(canvas.getByText('Expiring'))
+  },
+}
+
+export const CustomDelay: Story = {
+  render: () => (
+    <html.div style={centerStyles.center}>
+      <Tooltip.Root content="Instant tooltip" delay={0}>
+        <Tooltip.Trigger>
+          <Badge variant="info">No delay</Badge>
+        </Tooltip.Trigger>
+      </Tooltip.Root>
+      <Tooltip.Root content="Slow tooltip" delay={800}>
+        <Tooltip.Trigger>
+          <Badge variant="info">800ms delay</Badge>
+        </Tooltip.Trigger>
+      </Tooltip.Root>
+    </html.div>
+  ),
+}

package/src/components/Tooltip/Tooltip.tsx

@@ -0,0 +1,97 @@
+import {
+  type ReactNode,
+  createContext,
+  useContext,
+  useState,
+  useRef,
+  useCallback,
+  useId,
+} from 'react'
+import {html} from 'react-strict-dom'
+import {styles} from './styles.css'
+
+// --- Context ---
+
+type Placement = 'top' | 'bottom' | 'left' | 'right'
+
+interface TooltipContextValue {
+  open: boolean
+  show: () => void
+  hide: () => void
+  tooltipId: string
+  placement: Placement
+}
+
+const TooltipContext = createContext<TooltipContextValue | null>(null)
+
+function useTooltip() {
+  const ctx = useContext(TooltipContext)
+  if (!ctx) throw new Error('Tooltip compound components must be used within Tooltip.Root')
+  return ctx
+}
+
+// --- Root ---
+
+interface RootProps {
+  children: ReactNode
+  content: ReactNode
+  placement?: Placement
+  delay?: number
+}
+
+function Root({children, content, placement = 'top', delay = 300}: RootProps) {
+  const [open, setOpen] = useState(false)
+  const tooltipId = useId()
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+  const show = useCallback(() => {
+    if (timerRef.current) clearTimeout(timerRef.current)
+    timerRef.current = setTimeout(() => setOpen(true), delay)
+  }, [delay])
+
+  const hide = useCallback(() => {
+    if (timerRef.current) clearTimeout(timerRef.current)
+    timerRef.current = null
+    setOpen(false)
+  }, [])
+
+  return (
+    <TooltipContext.Provider value={{open, show, hide, tooltipId, placement}}>
+      <html.div style={styles.root}>
+        {children}
+        {open && (
+          <html.div id={tooltipId} role="tooltip" style={[styles.popup, styles[placement]]}>
+            {content}
+          </html.div>
+        )}
+      </html.div>
+    </TooltipContext.Provider>
+  )
+}
+
+// --- Trigger ---
+
+interface TriggerProps {
+  children: ReactNode
+}
+
+function Trigger({children}: TriggerProps) {
+  const {open, show, hide, tooltipId} = useTooltip()
+
+  return (
+    <html.div
+      onPointerEnter={show}
+      onPointerLeave={hide}
+      onFocus={show}
+      onBlur={hide}
+      aria-describedby={open ? tooltipId : undefined}
+    >
+      {children}
+    </html.div>
+  )
+}
+
+export const Tooltip = {
+  Root,
+  Trigger,
+}

package/src/components/Tooltip/styles.css.ts

@@ -0,0 +1,56 @@
+import {css} from 'react-strict-dom'
+import {colors} from '@duro-app/tokens/tokens/colors.css'
+import {spacing, radii} from '@duro-app/tokens/tokens/spacing.css'
+import {typography} from '@duro-app/tokens/tokens/typography.css'
+import {shadows} from '@duro-app/tokens/tokens/shadows.css'
+
+export const styles = css.create({
+  root: {
+    position: 'relative',
+    display: 'inline-flex',
+  },
+  popup: {
+    position: 'absolute',
+    zIndex: 50,
+    paddingTop: spacing.xs,
+    paddingBottom: spacing.xs,
+    paddingLeft: spacing.sm,
+    paddingRight: spacing.sm,
+    backgroundColor: colors.bgCard,
+    color: colors.text,
+    fontFamily: typography.fontFamily,
+    fontSize: typography.fontSizeXs,
+    lineHeight: typography.lineHeight,
+    borderRadius: radii.sm,
+    borderWidth: 1,
+    borderStyle: 'solid',
+    borderColor: colors.border,
+    boxShadow: shadows.md,
+    whiteSpace: 'nowrap',
+    pointerEvents: 'none',
+  },
+  top: {
+    bottom: '100%',
+    left: '50%',
+    transform: 'translateX(-50%)',
+    marginBottom: spacing.xs,
+  },
+  bottom: {
+    top: '100%',
+    left: '50%',
+    transform: 'translateX(-50%)',
+    marginTop: spacing.xs,
+  },
+  left: {
+    right: '100%',
+    top: '50%',
+    transform: 'translateY(-50%)',
+    marginRight: spacing.xs,
+  },
+  right: {
+    left: '100%',
+    top: '50%',
+    transform: 'translateY(-50%)',
+    marginLeft: spacing.xs,
+  },
+})

package/src/docs/Spacing.mdx

@@ -0,0 +1,80 @@
+{/* packages/ui/src/docs/Spacing.mdx */}
+import { Meta } from '@storybook/addon-docs/blocks'
+import { TokenTable } from './helpers'
+
+<Meta title="Foundations/Spacing/Overview" />
+
+# Spacing System
+
+The spacing system uses **three layers** — primitive tokens, semantic tokens, and layout components — to create consistent, maintainable spacing throughout the UI.
+
+## Philosophy
+
+- **24px baseline grid** — all spacing values are multiples or fractions of 24px, ensuring vertical rhythm.
+- **Primitive tokens** define the raw scale (`xs` through `xxxl`).
+- **Semantic tokens** give meaning to the scale: `stackMd`, `inlineSm`, `containerLg` tell you _where_ a value is used, not just _how big_ it is.
+- **Layout components** (`Stack`, `Inline`, `Cluster`, `Grid`) apply these tokens so you rarely write raw gap/padding values.
+
+## Primitive Scale
+
+These are the base spacing values imported from `@duro-app/tokens`:
+
+| Token  | Value |
+| ------ | ----- |
+| `xs`   | 4px   |
+| `sm`   | 8px   |
+| `ms`   | 12px  |
+| `md`   | 16px  |
+| `lg`   | 24px  |
+| `xl`   | 32px  |
+| `xxl`  | 48px  |
+| `xxxl` | 64px  |
+
+See the **Primitive Scale** story for a visual representation.
+
+## Semantic Tokens
+
+Semantic tokens map primitives to usage contexts:
+
+### Stack (vertical gaps)
+
+| Token     | Value |
+| --------- | ----- |
+| `stackXs` | 4px   |
+| `stackSm` | 8px   |
+| `stackMd` | 16px  |
+| `stackLg` | 24px  |
+| `stackXl` | 48px  |
+
+### Inline (horizontal gaps)
+
+| Token      | Value |
+| ---------- | ----- |
+| `inlineXs` | 4px   |
+| `inlineSm` | 8px   |
+| `inlineMd` | 16px  |
+| `inlineLg` | 24px  |
+
+### Container (insets/padding)
+
+| Token         | Value |
+| ------------- | ----- |
+| `containerSm` | 16px  |
+| `containerMd` | 24px  |
+| `containerLg` | 32px  |
+
+## When to use which layer
+
+| Scenario                                    | Use                                 |
+| ------------------------------------------- | ----------------------------------- |
+| Building a layout with vertical flow        | `<Stack gap="md">`                  |
+| Horizontal row of items                     | `<Inline gap="sm">`                 |
+| Card or section padding                     | `containerMd` / `containerLg` token |
+| One-off custom spacing in a component       | Primitive token (`spacing.lg`)      |
+| Responsive spacing based on container width | `useContainerQuery` hook            |
+
+## Responsive Spacing
+
+The `useContainerQuery` hook returns `compact`, `default`, or `spacious` based on the container width. Components can use this to adjust spacing at the component level rather than relying on viewport media queries.
+
+See the **Responsive Spacing** story for an interactive demo.

package/src/docs/Spacing.stories.tsx

@@ -0,0 +1,202 @@
+import type {Meta, StoryObj} from '@storybook/react'
+import {css, html} from 'react-strict-dom'
+import {spacing} from '@duro-app/tokens/tokens/spacing.css'
+import {colors} from '@duro-app/tokens/tokens/colors.css'
+import {Stack} from '../components/Stack/Stack'
+import {Inline} from '../components/Inline/Inline'
+import {useContainerQuery} from '../hooks/useContainerQuery'
+import {TokenTable} from './helpers'
+
+const primitiveTokens: Record<string, string> = {
+  xs: '4px',
+  sm: '8px',
+  ms: '12px',
+  md: '16px',
+  lg: '24px',
+  xl: '32px',
+  xxl: '48px',
+  xxxl: '64px',
+}
+
+const semanticTokens = {
+  stack: {stackXs: '4px', stackSm: '8px', stackMd: '16px', stackLg: '24px', stackXl: '48px'},
+  inline: {inlineXs: '4px', inlineSm: '8px', inlineMd: '16px', inlineLg: '24px'},
+  container: {containerSm: '16px', containerMd: '24px', containerLg: '32px'},
+}
+
+const meta: Meta = {
+  title: 'Foundations/Spacing',
+}
+
+export default meta
+
+const styles = css.create({
+  wrapper: {
+    maxWidth: 640,
+  },
+  hint: {
+    fontSize: '0.75rem',
+    color: colors.textMuted,
+    fontStyle: 'italic',
+  },
+  baselineRow: {
+    height: 24,
+    display: 'flex',
+    alignItems: 'center',
+    borderBottomWidth: 1,
+    borderBottomStyle: 'dashed',
+    borderBottomColor: 'rgba(0,0,0,0.1)',
+  },
+  baselineLabel: {
+    fontSize: '0.75rem',
+    fontFamily: 'monospace',
+    color: colors.textMuted,
+    width: 50,
+  },
+  baselineBlock: {
+    flexGrow: 1,
+    height: 24,
+    backgroundColor: colors.accent,
+    opacity: 0.15,
+    borderRadius: 2,
+  },
+  resizableContainer: {
+    resize: 'horizontal',
+    overflow: 'auto',
+    borderWidth: 2,
+    borderStyle: 'dashed',
+    borderColor: colors.border,
+    padding: spacing.md,
+    minWidth: 200,
+    maxWidth: '100%',
+    width: 600,
+  },
+  sizeLabel: {
+    fontSize: '1.5rem',
+    fontWeight: 700,
+    fontFamily: 'monospace',
+  },
+  sizeCompact: {
+    color: '#e67e22',
+  },
+  sizeDefault: {
+    color: colors.accent,
+  },
+  sizeSpacious: {
+    color: '#27ae60',
+  },
+  mappingRow: {
+    borderBottomWidth: 1,
+    borderBottomStyle: 'solid',
+    borderBottomColor: colors.border,
+    fontFamily: 'monospace',
+    fontSize: '0.8125rem',
+    paddingTop: spacing.xs,
+    paddingBottom: spacing.xs,
+  },
+  mappingLabel: {
+    color: colors.textMuted,
+  },
+  mappingValue: {
+    fontWeight: 600,
+  },
+})
+
+export const PrimitiveScale: StoryObj = {
+  render: () => (
+    <html.div style={styles.wrapper}>
+      <TokenTable tokens={primitiveTokens} label="Primitive Spacing Tokens" />
+    </html.div>
+  ),
+}
+
+export const SemanticTokens: StoryObj = {
+  render: () => (
+    <html.div style={styles.wrapper}>
+      <Stack gap="xl">
+        <TokenTable tokens={semanticTokens.stack} label="Stack (vertical)" />
+        <TokenTable tokens={semanticTokens.inline} label="Inline (horizontal)" />
+        <TokenTable tokens={semanticTokens.container} label="Container (insets)" />
+      </Stack>
+    </html.div>
+  ),
+}
+
+export const BaselineRhythm: StoryObj = {
+  render: () => {
+    const rows = Array.from({length: 12}, (_, i) => i)
+    return (
+      <html.div style={styles.wrapper}>
+        <Stack gap="md">
+          <html.p style={styles.hint}>
+            Each row is 24px tall — the baseline grid unit. Spacing tokens are multiples or
+            fractions of this grid.
+          </html.p>
+          <html.div>
+            {rows.map((i) => (
+              <html.div key={i} style={styles.baselineRow}>
+                <html.span style={styles.baselineLabel}>{(i + 1) * 24}px</html.span>
+                {i % 2 === 0 && <html.div style={styles.baselineBlock} />}
+              </html.div>
+            ))}
+          </html.div>
+        </Stack>
+      </html.div>
+    )
+  },
+}
+
+const spacingMappings: Record<string, Record<string, string>> = {
+  compact: {
+    stackGap: '4px – 8px',
+    inlineGap: '4px – 8px',
+    containerPad: '12px – 16px',
+  },
+  default: {
+    stackGap: '8px – 16px',
+    inlineGap: '8px – 16px',
+    containerPad: '16px – 24px',
+  },
+  spacious: {
+    stackGap: '16px – 24px',
+    inlineGap: '16px – 24px',
+    containerPad: '24px – 32px',
+  },
+}
+
+function ResponsiveDemo() {
+  const {ref, size} = useContainerQuery<HTMLDivElement>()
+  const sizeStyle =
+    size === 'compact'
+      ? styles.sizeCompact
+      : size === 'spacious'
+        ? styles.sizeSpacious
+        : styles.sizeDefault
+  const mapping = spacingMappings[size]
+
+  return (
+    <Stack gap="md">
+      <html.p style={styles.hint}>
+        Drag the right edge of the container below to resize it. Breakpoints: compact &lt; 480px,
+        default 480–768px, spacious &gt; 768px.
+      </html.p>
+      <html.div ref={ref} style={styles.resizableContainer}>
+        <Stack gap="sm">
+          <html.div style={[styles.sizeLabel, sizeStyle]}>{size}</html.div>
+          {Object.entries(mapping).map(([key, value]) => (
+            <html.div key={key} style={styles.mappingRow}>
+              <Inline justify="between">
+                <html.span style={styles.mappingLabel}>{key}</html.span>
+                <html.span style={styles.mappingValue}>{value}</html.span>
+              </Inline>
+            </html.div>
+          ))}
+        </Stack>
+      </html.div>
+    </Stack>
+  )
+}
+
+export const ResponsiveSpacing: StoryObj = {
+  render: () => <ResponsiveDemo />,
+}