@duro-app/ui 0.12.1 → 0.14.0

package/src/docs/Typography.mdx

@@ -0,0 +1,93 @@
+{/* packages/ui/src/docs/Typography.mdx */}
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title="Foundations/Typography/Overview" />
+
+# Typography System
+
+The typography system uses **three layers** — a primitive type scale, semantic presets, and components — to create consistent, expressive typography throughout the UI.
+
+## Philosophy
+
+- **9-step scale** — from 12px captions to 36px headings, each step has a matched line-height for vertical rhythm.
+- **24px baseline grid** — body text (16px/24px) and headings snap to multiples of the grid.
+- **Semantic presets** give meaning to the scale: `bodyMd`, `headingLg`, `caption` tell you _what_ the text is, not just _how big_.
+- **`Text` and `Heading` components** apply presets so you rarely write raw font styles.
+
+## Primitive Type Scale
+
+The base 9-step scale, defined in `typeScale`:
+
+| Step | Token       | Size | Line-height | Use case             |
+| ---- | ----------- | ---- | ----------- | -------------------- |
+| 1    | `fontSize1` | 12px | 16px        | Captions, badges     |
+| 2    | `fontSize2` | 13px | 20px        | Small UI             |
+| 3    | `fontSize3` | 14px | 20px        | Default UI (buttons) |
+| 4    | `fontSize4` | 16px | 24px        | Body text            |
+| 5    | `fontSize5` | 18px | 24px        | Body large           |
+| 6    | `fontSize6` | 20px | 28px        | Subheading           |
+| 7    | `fontSize7` | 24px | 32px        | Heading small        |
+| 8    | `fontSize8` | 30px | 36px        | Heading medium       |
+| 9    | `fontSize9` | 36px | 44px        | Heading large        |
+
+See the **Primitive Scale** story for live samples at each size.
+
+## Semantic Presets
+
+Presets compose scale tokens + weight + tracking into named styles via `typePresets`:
+
+### Body
+
+| Preset   | Size  | Weight | Use case                    |
+| -------- | ----- | ------ | --------------------------- |
+| `bodySm` | 14/20 | Normal | Compact UI text             |
+| `bodyMd` | 16/24 | Normal | Standard paragraphs         |
+| `bodyLg` | 18/24 | Normal | Emphasized intros, callouts |
+
+### UI
+
+| Preset     | Size  | Weight   | Notes                    |
+| ---------- | ----- | -------- | ------------------------ |
+| `caption`  | 12/16 | Normal   | Wide tracking            |
+| `label`    | 14/20 | Medium   | Form labels              |
+| `code`     | 14/20 | Normal   | Monospace font           |
+| `overline` | 12/16 | Semibold | Uppercase, wide tracking |
+
+### Heading
+
+| Preset      | Size  | Weight   | Tracking |
+| ----------- | ----- | -------- | -------- |
+| `headingSm` | 20/28 | Semibold | Tight    |
+| `headingMd` | 24/32 | Semibold | Tight    |
+| `headingLg` | 30/36 | Bold     | Tight    |
+| `headingXl` | 36/44 | Bold     | Tight    |
+
+### Display (fluid)
+
+| Preset      | Range   | Weight | Notes               |
+| ----------- | ------- | ------ | ------------------- |
+| `displaySm` | 36–48px | Bold   | Fluid via `clamp()` |
+| `displayMd` | 44–60px | Bold   | Fluid via `clamp()` |
+| `displayLg` | 56–72px | Bold   | Fluid via `clamp()` |
+
+See the **Fluid Display** story for a resizable demo.
+
+## Letter Spacing
+
+| Token                 | Value   | Use case               |
+| --------------------- | ------- | ---------------------- |
+| `letterSpacingTight`  | -0.02em | Headings, display text |
+| `letterSpacingNormal` | 0       | Body text              |
+| `letterSpacingWide`   | 0.04em  | Captions, overlines    |
+
+## When to use which layer
+
+| Scenario                                       | Use                                       |
+| ---------------------------------------------- | ----------------------------------------- |
+| Body text in a page or card                    | `<Text variant="bodyMd">`                 |
+| Section heading                                | `<Heading level={2}>`                     |
+| Hero or landing page title                     | `<Heading level={1} variant="displayLg">` |
+| Form label                                     | `<Text variant="label">`                  |
+| Inline code                                    | `<Text variant="code">`                   |
+| Custom component needing raw font size         | `typeScale.fontSize4` token               |
+| Composing a one-off style with preset defaults | `typePresets.bodyMd` in `css.create()`    |

package/src/docs/Typography.stories.tsx

@@ -0,0 +1,211 @@
+import type {Meta, StoryObj} from '@storybook/react'
+import {css, html} from 'react-strict-dom'
+import {colors} from '@duro-app/tokens/tokens/colors.css'
+import {spacing} from '@duro-app/tokens/tokens/spacing.css'
+import {typePresets} from '@duro-app/tokens/tokens/type-presets.css'
+import {Stack} from '../components/Stack/Stack'
+import {Text} from '../components/Text/Text'
+import {Heading} from '../components/Heading/Heading'
+import {TypeScaleTable} from './helpers'
+
+const meta: Meta = {
+  title: 'Foundations/Typography',
+}
+
+export default meta
+
+const scaleRows = [
+  {step: 1, token: 'fontSize1', size: '0.75rem', lineHeight: '1rem'},
+  {step: 2, token: 'fontSize2', size: '0.8125rem', lineHeight: '1.25rem'},
+  {step: 3, token: 'fontSize3', size: '0.875rem', lineHeight: '1.25rem'},
+  {step: 4, token: 'fontSize4', size: '1rem', lineHeight: '1.5rem'},
+  {step: 5, token: 'fontSize5', size: '1.125rem', lineHeight: '1.5rem'},
+  {step: 6, token: 'fontSize6', size: '1.25rem', lineHeight: '1.75rem'},
+  {step: 7, token: 'fontSize7', size: '1.5rem', lineHeight: '2rem'},
+  {step: 8, token: 'fontSize8', size: '1.875rem', lineHeight: '2.25rem'},
+  {step: 9, token: 'fontSize9', size: '2.25rem', lineHeight: '2.75rem'},
+]
+
+export const PrimitiveScale: StoryObj = {
+  render: () => (
+    <html.div style={localStyles.wrapper}>
+      <TypeScaleTable rows={scaleRows} label="9-Step Type Scale" />
+    </html.div>
+  ),
+}
+
+const presetEntries: Array<{name: string; key: keyof typeof typePresets; sample: string}> = [
+  {name: 'bodySm', key: 'bodySm', sample: 'Body small — default UI text at 14px.'},
+  {name: 'bodyMd', key: 'bodyMd', sample: 'Body medium — standard body text at 16px.'},
+  {name: 'bodyLg', key: 'bodyLg', sample: 'Body large — emphasized body text at 18px.'},
+  {name: 'caption', key: 'caption', sample: 'Caption — supplementary info at 12px.'},
+  {name: 'label', key: 'label', sample: 'Label — form labels and UI labels at 14px medium.'},
+  {name: 'code', key: 'code', sample: 'const x = "Code — monospace for inline code"'},
+  {name: 'overline', key: 'overline', sample: 'Overline — section labels, uppercase'},
+  {name: 'headingSm', key: 'headingSm', sample: 'Heading Small'},
+  {name: 'headingMd', key: 'headingMd', sample: 'Heading Medium'},
+  {name: 'headingLg', key: 'headingLg', sample: 'Heading Large'},
+  {name: 'headingXl', key: 'headingXl', sample: 'Heading Extra Large'},
+  {name: 'displaySm', key: 'displaySm', sample: 'Display Small'},
+  {name: 'displayMd', key: 'displayMd', sample: 'Display Medium'},
+  {name: 'displayLg', key: 'displayLg', sample: 'Display Large'},
+]
+
+export const SemanticPresets: StoryObj = {
+  render: () => (
+    <html.div style={localStyles.wrapper}>
+      <Stack gap="lg">
+        {presetEntries.map(({name, key, sample}) => (
+          <html.div key={name}>
+            <html.span style={localStyles.presetLabel}>{name}</html.span>
+            <html.div style={typePresets[key]}>{sample}</html.div>
+          </html.div>
+        ))}
+      </Stack>
+    </html.div>
+  ),
+}
+
+export const BaselineGrid: StoryObj = {
+  render: () => {
+    const gridLines = Array.from({length: 8}, (_, i) => i)
+    return (
+      <html.div style={localStyles.wrapper}>
+        <Stack gap="md">
+          <html.p style={localStyles.hint}>
+            Text overlaid on a 24px baseline grid showing vertical rhythm alignment.
+          </html.p>
+          <html.div style={localStyles.gridContainer}>
+            {gridLines.map((i) => (
+              <html.div key={i} style={localStyles.gridLine} />
+            ))}
+            <html.div style={localStyles.gridOverlay}>
+              <html.div style={typePresets.bodyMd}>Body medium sits on the 24px grid.</html.div>
+              <html.div style={typePresets.headingMd}>Heading medium aligns too.</html.div>
+              <html.div style={typePresets.bodySm}>Body small text flows naturally below.</html.div>
+            </html.div>
+          </html.div>
+        </Stack>
+      </html.div>
+    )
+  },
+}
+
+export const FluidDisplay: StoryObj = {
+  render: () => (
+    <html.div style={localStyles.wrapper}>
+      <Stack gap="md">
+        <html.p style={localStyles.hint}>
+          Drag the right edge of the container to resize. Display headings scale fluidly between
+          their min and max sizes using clamp().
+        </html.p>
+        <html.div style={localStyles.resizableContainer}>
+          <Stack gap="md">
+            <html.div style={typePresets.displayLg}>Display Large</html.div>
+            <html.div style={typePresets.displayMd}>Display Medium</html.div>
+            <html.div style={typePresets.displaySm}>Display Small</html.div>
+          </Stack>
+        </html.div>
+      </Stack>
+    </html.div>
+  ),
+}
+
+export const HeadingLevels: StoryObj = {
+  render: () => (
+    <html.div style={localStyles.wrapper}>
+      <Stack gap="lg">
+        <Heading level={1}>Heading Level 1 — headingXl</Heading>
+        <Heading level={2}>Heading Level 2 — headingLg</Heading>
+        <Heading level={3}>Heading Level 3 — headingMd</Heading>
+        <Heading level={4}>Heading Level 4 — headingSm</Heading>
+        <Heading level={5}>Heading Level 5 — headingSm</Heading>
+        <Heading level={6}>Heading Level 6 — headingSm</Heading>
+      </Stack>
+    </html.div>
+  ),
+}
+
+export const TextVariants: StoryObj = {
+  render: () => (
+    <html.div style={localStyles.wrapper}>
+      <Stack gap="lg">
+        <Text variant="bodyMd" as="p">
+          Body medium — the default paragraph text.
+        </Text>
+        <Text variant="bodySm" as="p">
+          Body small — compact UI text for secondary content.
+        </Text>
+        <Text variant="bodyLg" as="p">
+          Body large — emphasized text for intros or callouts.
+        </Text>
+        <Text variant="caption" color="muted">
+          Caption — timestamps, footnotes, metadata
+        </Text>
+        <Text variant="label">Label — form labels and input descriptions</Text>
+        <Text variant="code">const greeting = &quot;Hello, world!&quot;</Text>
+        <Text variant="overline" color="muted">
+          Overline — section dividers
+        </Text>
+        <Stack gap="sm">
+          <Text variant="bodyMd" color="accent">
+            Accent colored text
+          </Text>
+          <Text variant="bodyMd" color="error">
+            Error colored text
+          </Text>
+          <Text variant="bodyMd" color="success">
+            Success colored text
+          </Text>
+          <Text variant="bodyMd" color="warning">
+            Warning colored text
+          </Text>
+        </Stack>
+      </Stack>
+    </html.div>
+  ),
+}
+
+const localStyles = css.create({
+  wrapper: {
+    maxWidth: 720,
+  },
+  hint: {
+    fontSize: '0.75rem',
+    color: colors.textMuted,
+    fontStyle: 'italic',
+  },
+  presetLabel: {
+    display: 'block',
+    fontSize: '0.6875rem',
+    fontFamily: 'monospace',
+    color: colors.textMuted,
+    marginBottom: 4,
+  },
+  gridContainer: {
+    position: 'relative',
+  },
+  gridLine: {
+    height: 24,
+    borderBottomWidth: 1,
+    borderBottomStyle: 'dashed',
+    borderBottomColor: 'rgba(0,0,0,0.08)',
+  },
+  gridOverlay: {
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    right: 0,
+  },
+  resizableContainer: {
+    resize: 'horizontal',
+    overflow: 'auto',
+    borderWidth: 2,
+    borderStyle: 'dashed',
+    borderColor: colors.border,
+    padding: spacing.md,
+    minWidth: 280,
+    maxWidth: '100%',
+    width: 700,
+  },
+})

package/src/docs/helpers.tsx

@@ -0,0 +1,135 @@
+import {css, html} from 'react-strict-dom'
+import {colors} from '@duro-app/tokens/tokens/colors.css'
+import {typography, typeScale} from '@duro-app/tokens/tokens/typography.css'
+import {Table} from '../components/Table/Table'
+
+const styles = css.create({
+  bar: {
+    height: 12,
+    borderRadius: 2,
+    backgroundColor: colors.accent,
+  },
+  label: {
+    fontSize: '1rem',
+    fontWeight: 600,
+    marginBottom: 4,
+  },
+  mono: {
+    fontFamily: 'monospace',
+  },
+  muted: {
+    fontFamily: 'monospace',
+    color: colors.textMuted,
+  },
+})
+
+const dynamicStyles = css.create({
+  barWidth: (width: string) => ({
+    width,
+  }),
+  typeSample: (fontSize: string, lineHeight: string) => ({
+    fontFamily: typography.fontFamily,
+    whiteSpace: 'nowrap' as const,
+    fontSize,
+    lineHeight,
+  }),
+})
+
+interface SpacingBarProps {
+  value: string
+}
+
+export function SpacingBar({value}: SpacingBarProps) {
+  return <html.div style={[styles.bar, dynamicStyles.barWidth(value)]} />
+}
+
+interface TokenTableProps {
+  tokens: Record<string, string>
+  label?: string
+}
+
+interface TypeScaleRow {
+  step: number
+  token: string
+  size: string
+  lineHeight: string
+}
+
+interface TypeScaleTableProps {
+  rows: TypeScaleRow[]
+  label?: string
+}
+
+export function TypeScaleTable({rows, label}: TypeScaleTableProps) {
+  return (
+    <html.div>
+      {label && <html.h3 style={styles.label}>{label}</html.h3>}
+      <Table.Root columns={4} variant="striped" size="sm">
+        <Table.Header>
+          <Table.Row>
+            <Table.HeaderCell>Step</Table.HeaderCell>
+            <Table.HeaderCell>Token</Table.HeaderCell>
+            <Table.HeaderCell>Size / Line-height</Table.HeaderCell>
+            <Table.HeaderCell>Sample</Table.HeaderCell>
+          </Table.Row>
+        </Table.Header>
+        <Table.Body>
+          {rows.map((row) => (
+            <Table.Row key={row.step}>
+              <Table.Cell>
+                <html.span style={styles.mono}>{row.step}</html.span>
+              </Table.Cell>
+              <Table.Cell>
+                <html.span style={styles.mono}>{row.token}</html.span>
+              </Table.Cell>
+              <Table.Cell>
+                <html.span style={styles.muted}>
+                  {row.size} / {row.lineHeight}
+                </html.span>
+              </Table.Cell>
+              <Table.Cell>
+                <html.span style={dynamicStyles.typeSample(row.size, row.lineHeight)}>
+                  The quick brown fox
+                </html.span>
+              </Table.Cell>
+            </Table.Row>
+          ))}
+        </Table.Body>
+      </Table.Root>
+    </html.div>
+  )
+}
+
+export function TokenTable({tokens, label}: TokenTableProps) {
+  const entries = Object.entries(tokens)
+
+  return (
+    <html.div>
+      {label && <html.h3 style={styles.label}>{label}</html.h3>}
+      <Table.Root columns={3} variant="striped" size="sm">
+        <Table.Header>
+          <Table.Row>
+            <Table.HeaderCell>Token</Table.HeaderCell>
+            <Table.HeaderCell>Value</Table.HeaderCell>
+            <Table.HeaderCell>Preview</Table.HeaderCell>
+          </Table.Row>
+        </Table.Header>
+        <Table.Body>
+          {entries.map(([name, value]) => (
+            <Table.Row key={name}>
+              <Table.Cell>
+                <html.span style={styles.mono}>{name}</html.span>
+              </Table.Cell>
+              <Table.Cell>
+                <html.span style={styles.muted}>{value}</html.span>
+              </Table.Cell>
+              <Table.Cell>
+                <SpacingBar value={value} />
+              </Table.Cell>
+            </Table.Row>
+          ))}
+        </Table.Body>
+      </Table.Root>
+    </html.div>
+  )
+}

package/src/hooks/useContainerQuery.ts

@@ -0,0 +1,54 @@
+import {useRef, useState, useEffect} from 'react'
+
+export type ContainerSize = 'compact' | 'default' | 'spacious'
+
+interface UseContainerQueryOptions {
+  compactBelow?: number
+  spaciousAbove?: number
+}
+
+export function useContainerQuery<T extends HTMLElement = HTMLElement>(
+  options: UseContainerQueryOptions = {},
+): {
+  ref: React.RefObject<T | null>
+  size: ContainerSize
+} {
+  const {compactBelow = 480, spaciousAbove = 768} = options
+  const ref = useRef<T | null>(null)
+  const [size, setSize] = useState<ContainerSize>('default')
+
+  useEffect(() => {
+    const element = ref.current
+    if (!element) return
+
+    let rafId: number | null = null
+
+    const observer = new ResizeObserver((entries) => {
+      if (rafId !== null) cancelAnimationFrame(rafId)
+
+      rafId = requestAnimationFrame(() => {
+        const entry = entries[0]
+        if (!entry) return
+
+        const width = entry.contentBoxSize?.[0]?.inlineSize ?? entry.contentRect.width
+
+        if (width < compactBelow) {
+          setSize('compact')
+        } else if (width >= spaciousAbove) {
+          setSize('spacious')
+        } else {
+          setSize('default')
+        }
+      })
+    })
+
+    observer.observe(element)
+
+    return () => {
+      observer.disconnect()
+      if (rafId !== null) cancelAnimationFrame(rafId)
+    }
+  }, [compactBelow, spaciousAbove])
+
+  return {ref, size}
+}

package/src/hooks/useControllableValue.ts

@@ -0,0 +1,18 @@
+import {useState, useCallback} from 'react'
+
+export function useControllableValue<T>(
+  controlledValue: T | undefined,
+  defaultValue: T,
+  onChange?: (value: T) => void,
+) {
+  const [internal, setInternal] = useState(defaultValue)
+  const value = controlledValue !== undefined ? controlledValue : internal
+  const setValue = useCallback(
+    (v: T) => {
+      if (controlledValue === undefined) setInternal(v)
+      onChange?.(v)
+    },
+    [controlledValue, onChange],
+  )
+  return [value, setValue] as const
+}

package/src/index.ts

@@ -0,0 +1,56 @@
+import './strict.css'
+
+// Components
+export {Alert, type AlertVariant} from './components/Alert/Alert'
+export {Icon, type IconName} from './components/Icon'
+export {Badge, type BadgeVariant, type BadgeSize} from './components/Badge/Badge'
+export {Button, type ButtonVariant, type ButtonSize} from './components/Button/Button'
+export {Callout, type CalloutVariant} from './components/Callout/Callout'
+export {Card, type CardVariant, type CardSize} from './components/Card/Card'
+export {Checkbox} from './components/Checkbox/Checkbox'
+export {EmptyState} from './components/EmptyState/EmptyState'
+export {Heading, type HeadingVariant} from './components/Heading/Heading'
+export {Field} from './components/Field/Field'
+export {Fieldset, type FieldsetGap} from './components/Fieldset/Fieldset'
+export {Input, type InputVariant} from './components/Input/Input'
+export {InputGroup} from './components/InputGroup/InputGroup'
+export {
+  LinkButton,
+  type LinkButtonVariant,
+  type LinkButtonSize,
+} from './components/LinkButton/LinkButton'
+export {Menu} from './components/Menu/Menu'
+export {ScrollArea} from './components/ScrollArea/ScrollArea'
+export {Select} from './components/Select/Select'
+export {SideNav} from './components/SideNav/SideNav'
+export {Spinner, type SpinnerSize} from './components/Spinner/Spinner'
+export {
+  StatusIcon,
+  type StatusIconName,
+  type StatusIconVariant,
+} from './components/StatusIcon/StatusIcon'
+export {Table, type TableVariant, type TableSize} from './components/Table/Table'
+export {Tabs} from './components/Tabs/Tabs'
+export {Textarea, type TextareaVariant} from './components/Textarea/Textarea'
+export {ThemeProvider, type ThemeName} from './components/ThemeProvider/ThemeProvider'
+export {Text, type TextVariant, type TextColor} from './components/Text/Text'
+export {Toggle, type ToggleSize} from './components/Toggle/Toggle'
+export {ToggleGroup} from './components/ToggleGroup/ToggleGroup'
+export {Tooltip} from './components/Tooltip/Tooltip'
+export {Switch} from './components/Switch/Switch'
+
+// Layout primitives
+export {Stack, type SpacingKey} from './components/Stack/Stack'
+export {Inline} from './components/Inline/Inline'
+export {Cluster} from './components/Cluster/Cluster'
+export {Grid} from './components/Grid/Grid'
+export {PageShell, type PageShellMaxWidth, type PageShellPadding} from './components/PageShell'
+
+// Hooks
+export {useContainerQuery, type ContainerSize} from './hooks/useContainerQuery'
+
+// Tokens — import directly from @duro-app/tokens with deep imports:
+//   import { colors } from '@duro-app/tokens/tokens/colors.css'
+//   import { spacing, radii } from '@duro-app/tokens/tokens/spacing.css'
+// Barrel re-exports removed: StyleX's babel plugin cannot resolve
+// css.defineVars through barrel re-exports.

package/src/stubs/assets-registry.ts

@@ -0,0 +1,3 @@
+export function getAssetByID(_id: number) {
+  return null
+}