@peerproblem/sw3-ui 0.0.0-stage → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (144) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +109 -2
  3. package/agent/components/accordion.md +95 -0
  4. package/agent/components/action-square.md +106 -0
  5. package/agent/components/agent-bridge.md +87 -0
  6. package/agent/components/agent-console.md +123 -0
  7. package/agent/components/alert-dialog.md +82 -0
  8. package/agent/components/app-shell.md +105 -0
  9. package/agent/components/area-chart.md +56 -0
  10. package/agent/components/async-options.md +47 -0
  11. package/agent/components/autocomplete.md +69 -0
  12. package/agent/components/avatar.md +88 -0
  13. package/agent/components/badge.md +51 -0
  14. package/agent/components/bar-chart.md +56 -0
  15. package/agent/components/bar-list.md +49 -0
  16. package/agent/components/breadcrumbs.md +43 -0
  17. package/agent/components/button.md +109 -0
  18. package/agent/components/calendar.md +114 -0
  19. package/agent/components/canvas.md +105 -0
  20. package/agent/components/card.md +78 -0
  21. package/agent/components/carousel.md +113 -0
  22. package/agent/components/chart-card.md +41 -0
  23. package/agent/components/chart-surface.md +56 -0
  24. package/agent/components/checkbox.md +88 -0
  25. package/agent/components/citation-chip.md +61 -0
  26. package/agent/components/collapsible.md +69 -0
  27. package/agent/components/color-picker.md +82 -0
  28. package/agent/components/combobox.md +104 -0
  29. package/agent/components/command.md +92 -0
  30. package/agent/components/dashboard-grid.md +73 -0
  31. package/agent/components/date-input.md +87 -0
  32. package/agent/components/date-picker.md +122 -0
  33. package/agent/components/dialog.md +97 -0
  34. package/agent/components/donut-chart.md +50 -0
  35. package/agent/components/drawer.md +101 -0
  36. package/agent/components/empty-state.md +52 -0
  37. package/agent/components/field.md +80 -0
  38. package/agent/components/file-input.md +84 -0
  39. package/agent/components/hover-card.md +64 -0
  40. package/agent/components/image-cropper.md +77 -0
  41. package/agent/components/input.md +49 -0
  42. package/agent/components/label.md +53 -0
  43. package/agent/components/line-chart.md +60 -0
  44. package/agent/components/listbox.md +84 -0
  45. package/agent/components/map-view.md +104 -0
  46. package/agent/components/menu.md +117 -0
  47. package/agent/components/menubar.md +67 -0
  48. package/agent/components/meter.md +59 -0
  49. package/agent/components/navigation-menu.md +98 -0
  50. package/agent/components/number-input.md +81 -0
  51. package/agent/components/otp-input.md +67 -0
  52. package/agent/components/pagination.md +80 -0
  53. package/agent/components/password-input.md +67 -0
  54. package/agent/components/pill-button.md +116 -0
  55. package/agent/components/popover.md +85 -0
  56. package/agent/components/poster-card.md +61 -0
  57. package/agent/components/preferences.md +92 -0
  58. package/agent/components/progress.md +63 -0
  59. package/agent/components/provider.md +47 -0
  60. package/agent/components/radio.md +91 -0
  61. package/agent/components/rating.md +66 -0
  62. package/agent/components/reorder.md +61 -0
  63. package/agent/components/resizable.md +87 -0
  64. package/agent/components/scatter-chart.md +49 -0
  65. package/agent/components/scroll-area.md +81 -0
  66. package/agent/components/segmented-control.md +56 -0
  67. package/agent/components/select.md +130 -0
  68. package/agent/components/separator.md +60 -0
  69. package/agent/components/shortcuts.md +50 -0
  70. package/agent/components/sidebar-nav.md +68 -0
  71. package/agent/components/skeleton.md +58 -0
  72. package/agent/components/slider.md +79 -0
  73. package/agent/components/sparkline.md +39 -0
  74. package/agent/components/squircle.md +58 -0
  75. package/agent/components/stat.md +58 -0
  76. package/agent/components/switch.md +48 -0
  77. package/agent/components/table.md +58 -0
  78. package/agent/components/tabs.md +108 -0
  79. package/agent/components/textarea.md +68 -0
  80. package/agent/components/time-input.md +84 -0
  81. package/agent/components/timeline.md +91 -0
  82. package/agent/components/toast.md +85 -0
  83. package/agent/components/toggle.md +76 -0
  84. package/agent/components/token-input.md +66 -0
  85. package/agent/components/toolbar.md +76 -0
  86. package/agent/components/tooltip.md +83 -0
  87. package/agent/components/tracker.md +47 -0
  88. package/agent/components/tree.md +87 -0
  89. package/agent/components/treemap.md +72 -0
  90. package/agent/components/trend-chart.md +80 -0
  91. package/agent/components/trigger-menu.md +67 -0
  92. package/agent/components/typography.md +51 -0
  93. package/agent/components/waterfall.md +78 -0
  94. package/agent/components/week-schedule.md +113 -0
  95. package/agent/llms/actions-and-layout.txt +1749 -0
  96. package/agent/llms/agents.txt +505 -0
  97. package/agent/llms/charts.txt +778 -0
  98. package/agent/llms/dashboards.txt +457 -0
  99. package/agent/llms/extend.txt +132 -0
  100. package/agent/llms/extras.txt +527 -0
  101. package/agent/llms/forms.txt +2152 -0
  102. package/agent/llms/foundations.txt +674 -0
  103. package/agent/llms/hooks.txt +178 -0
  104. package/agent/llms/maps.txt +229 -0
  105. package/agent/llms/overlays-and-navigation.txt +1167 -0
  106. package/agent/llms-full.txt +8717 -0
  107. package/agent/llms.txt +145 -0
  108. package/agent/registry.json +11289 -0
  109. package/agent/tokens.md +66 -0
  110. package/dist/agent/index.d.ts +235 -0
  111. package/dist/agent/index.js +21 -0
  112. package/dist/card-Ipm-Cj5f.d.ts +490 -0
  113. package/dist/charts/index.d.ts +289 -0
  114. package/dist/charts/index.js +815 -0
  115. package/dist/check/cli.d.ts +1 -0
  116. package/dist/check/cli.js +48 -0
  117. package/dist/check/rendered.d.ts +11 -0
  118. package/dist/check/rendered.js +77 -0
  119. package/dist/check/source.d.ts +13 -0
  120. package/dist/check/source.js +182 -0
  121. package/dist/chunk-3DXBM65D.js +65 -0
  122. package/dist/chunk-3H5X4ZP6.js +55 -0
  123. package/dist/chunk-6XC4BC5C.js +92 -0
  124. package/dist/chunk-7H6TEAWD.js +507 -0
  125. package/dist/chunk-I63ZTJOI.js +1089 -0
  126. package/dist/chunk-JCIRUM4W.js +33 -0
  127. package/dist/chunk-LTBEHZ3P.js +25 -0
  128. package/dist/chunk-QDPPLO4U.js +60 -0
  129. package/dist/chunk-U2XFBPU4.js +56 -0
  130. package/dist/chunk-UY2WH5AY.js +681 -0
  131. package/dist/extras.d.ts +203 -0
  132. package/dist/extras.js +904 -0
  133. package/dist/icons-BJiGEAnU.d.ts +68 -0
  134. package/dist/index.d.ts +3737 -0
  135. package/dist/index.js +14477 -0
  136. package/dist/map/index.d.ts +115 -0
  137. package/dist/map/index.js +394 -0
  138. package/dist/meta/index.d.ts +3314 -0
  139. package/dist/meta/index.js +5106 -0
  140. package/dist/rules-1RIZ_JZr.d.ts +38 -0
  141. package/dist/styles.css +4037 -0
  142. package/dist/themes/calm.css +42 -0
  143. package/dist/themes/frost.css +40 -0
  144. package/package.json +142 -4
@@ -0,0 +1,51 @@
1
+ # Typography
2
+
3
+ > Display, Outline, Heading, Text, Link, Caption and Kbd: the type scale for pages, panels and inline text.
4
+
5
+ Category: foundation · Status: stable · Slug: `typography`
6
+
7
+ ```tsx
8
+ import { Display, Outline, Heading, Text, Link, Caption, Kbd } from '@peerproblem/sw3-ui'
9
+ ```
10
+
11
+ ## When to use
12
+ - Display for heroes; Heading for sections; Text for copy; Caption for mono labels.
13
+
14
+ ## Avoid
15
+ - Picking heading levels by size. Set `as` from the outline and `size` from emphasis.
16
+ - ALL CAPS outside Caption.
17
+ - A horizontal rule from typography. Use Separator.
18
+
19
+ ## Props
20
+
21
+ | Prop | Type | Default | Description |
22
+ | --- | --- | --- | --- |
23
+ | `Display.size` | `'md' \| 'lg' \| 'xl'` | `'lg'` | Fluid sizes; xl is poster scale. |
24
+ | `Heading.size` | `'sm' \| 'md' \| 'lg'` | `'md'` | |
25
+ | `Text.size` | `'sm' \| 'base' \| 'lg'` | `'base'` | lg = lede paragraph. |
26
+ | `Text.tone` | `'default' \| 'muted' \| 'subtle'` | `'default'` | |
27
+ | `Display.as` | `'h1' \| 'h2' \| 'p' \| 'div'` | `'h1'` | Choose the hero heading level, or use p for decorative copy under a page title. |
28
+ | `Heading.as` | `'h1' \| 'h2' \| 'h3' \| 'h4' \| 'h5' \| 'h6'` | `'h2'` | Choose the heading level from the document hierarchy. Use size for visual emphasis. |
29
+ | `Link.href` * | `string` | | Inline link destination. Supports standard anchor attributes. |
30
+ | `Text.as` | `'p' \| 'span' \| 'div'` | `'p'` | Use span for inline text. |
31
+
32
+ ## Examples
33
+
34
+ ### Section intro
35
+
36
+ ```tsx
37
+ <Separator tone="frame" />
38
+ <Heading as="h2" size="lg">Behaviors? What are those?</Heading>
39
+ <Text size="lg" tone="subtle">They are the pieces that make a component work.</Text>
40
+ <Caption>Tap a title to open it</Caption>
41
+ ```
42
+
43
+ ## Rules
44
+ - Use Display for the primary hero and Heading for page and section titles. Choose the HTML heading level independently of size.
45
+ - Look (default theme): headings at weight 450 with tight tracking, Geist and Geist Mono. Change the typefaces with --sw-font-sans and --sw-font-mono.
46
+ - Use Caption for short supporting metadata and Text for instructions.
47
+ - Kbd is a flat 1px frame.
48
+
49
+ ## DOM contract (for agents operating the page)
50
+
51
+ - Selector: `[data-sw="display"], [data-sw="heading"], [data-sw="text"], [data-sw="caption"]`
@@ -0,0 +1,78 @@
1
+ # Waterfall
2
+
3
+ > Trace or network spans as bars on one shared time axis; nested spans expand and collapse (treegrid), bars are colored by kind with the chart palette, and hover shows details.
4
+
5
+ Category: display · Status: beta · Slug: `waterfall`
6
+
7
+ ```tsx
8
+ import { Waterfall, type WaterfallSpan } from '@peerproblem/sw3-ui'
9
+ ```
10
+
11
+ ## When to use
12
+ - Agent run traces (LLM calls, tool calls, DB queries).
13
+ - Network request waterfalls.
14
+ - Any set of timed, possibly nested operations.
15
+
16
+ ## Avoid
17
+ - Values over time (traffic, latency trends). Use a LineChart or AreaChart in a ChartCard.
18
+ - Ordered events without durations. Use Timeline.
19
+ - More than a few hundred visible rows. Collapse by default (the default) or filter first.
20
+
21
+ ## Props
22
+
23
+ | Prop | Type | Default | Description |
24
+ | --- | --- | --- | --- |
25
+ | `items` * | `WaterfallSpan[] ({ value, label, start, duration, kind?, detail?, children? })` | | Spans in ms on one clock; `children` are nested spans. |
26
+ | `aria-label` * | `string` | | Names the grid, e.g. "Trace for run 42". |
27
+ | `range` | `[number, number]` | | Axis start/end in ms. Default: earliest start (or 0) to latest end. Change it to zoom. |
28
+ | `value / defaultValue / onValueChange` | `string \| null` | | Selected span (click, Enter or Space). |
29
+ | `expanded / defaultExpanded / onExpandedChange` | `string[] (defaultExpanded also 'all')` | `[] (collapsed)` | Which spans show their children. |
30
+ | `kinds` | `Record<string, number \| string>` | | kind → chart color index 1–8 (var(--sw-chart-N)) or a CSS color. Unlisted kinds get the next color. |
31
+ | `columns` | `{ key, header, render(span), width? }[]` | | Extra columns between the name and the bars. |
32
+ | `marks` | `{ time: number; label: string }[]` | | Dashed vertical lines, e.g. first token. |
33
+ | `maxTicks` | `number` | `5` | Most axis ticks (round times). |
34
+ | `format` | `(ms: number) => string` | `"820 ms" / "1.24 s"` | Time formatting for the axis, labels and details. |
35
+ | `nameHeader` | `ReactNode` | `'Span'` | Header of the name column. |
36
+ | `legend` | `boolean` | `when >1 kind` | Legend of kinds under the grid. |
37
+ | `framed` | `boolean` | `true` | Own 1px squircle frame with a 4px inset; row hover/selected fills are concentric with it. Set false inside a surface that already frames it. |
38
+
39
+ ## Examples
40
+
41
+ ### Agent trace
42
+
43
+ ```tsx
44
+ <Waterfall aria-label="Trace for run 4821" defaultExpanded="all"
45
+ kinds={{ llm: 1, db: 3, http: 4, tool: 5 }}
46
+ items={[{ value: 'run', label: 'agent.run', start: 0, duration: 2840, children: [
47
+ { value: 'plan', label: 'plan', start: 12, duration: 620, kind: 'llm' },
48
+ { value: 'q', label: 'SELECT docs', start: 650, duration: 380, kind: 'db', detail: { Rows: '24' } },
49
+ ] }]} />
50
+ ```
51
+
52
+ ### Network requests with a column
53
+
54
+ ```tsx
55
+ <Waterfall aria-label="Network" items={requests}
56
+ columns={[{ key: 'status', header: 'Status', width: '48px', render: (r) => r.detail?.Status }]}
57
+ marks={[{ time: 820, label: 'DOMContentLoaded' }]} />
58
+ ```
59
+
60
+ ## Rules
61
+ - Colors come from the chart palette by `kind`; keep kinds few (≤ 6) and map them with `kinds` so colors stay stable.
62
+ - Put it full width; the bars need room. On phones the name column narrows automatically.
63
+ - Use `detail` for extra facts (status, rows, tokens) instead of long labels.
64
+ - Framed by default — do not wrap it in a Card. The selected row is a neutral fill + 500 label, not accent.
65
+
66
+ ## Accessibility
67
+ - WAI-ARIA treegrid: rows have aria-level, aria-posinset, aria-setsize, aria-expanded (branches) and aria-selected. Each bar cell reads "Starts at X, lasts Y".
68
+ - One tab stop. Up/Down, Home/End, Page Up/Down move; Right expands then moves to the first child; Left collapses then moves to the parent; Enter/Space selects; typing jumps by label.
69
+
70
+ ## DOM contract (for agents operating the page)
71
+
72
+ - Selector: `[data-sw="waterfall"]`
73
+ - `data-state (row)`: 'open' | 'closed' on spans with children
74
+ - `data-selected / aria-selected (row)`: the selected span
75
+ - `data-value (row)`: span value
76
+ - How to operate: Agent bridge: expand(value), collapse(value), toggle(value), expandAll(), collapseAll(), select(value) / setValue(value); items = every span with start + duration. DOM: rows are [data-sw="waterfall-row"][data-value]; click [data-sw="waterfall-indicator"] to toggle.
77
+
78
+ Related: `timeline`, `line-chart`, `chart-card`
@@ -0,0 +1,113 @@
1
+ # WeekSchedule
2
+
3
+ > A week board — day columns × hour rows with meeting, focus and away blocks you drag to move, drag by the bottom edge to resize, or nudge with arrow keys; shows the hours booked.
4
+
5
+ Category: extras · Status: beta · Slug: `week-schedule`
6
+
7
+ ```tsx
8
+ import { WeekSchedule } from '@peerproblem/sw3-ui/extras'
9
+ ```
10
+
11
+ ## When to use
12
+ - Planning a working week: placing meetings and focus blocks, seeing what is booked at a glance.
13
+ - Letting a person (or an agent) reschedule a handful of events by dragging or by keyboard.
14
+ - A compact, read-only "my week" view on a dashboard (readOnly, summary off).
15
+
16
+ ## Avoid
17
+ - Month views or picking a single date — use Calendar / DatePicker.
18
+ - Many overlapping events per slot (shared team calendars) — events in the same slot overlap here instead of splitting into lanes.
19
+ - Choosing one time — use TimeInput.
20
+ - Long ordered histories — use Timeline.
21
+
22
+ ## Props
23
+
24
+ | Prop | Type | Default | Description |
25
+ | --- | --- | --- | --- |
26
+ | `events` | `WeekEvent[]` | | Controlled events: { id, title, day (0-based into days), start, end (minutes from midnight), kind?: "meeting" | "focus" | "away" }. |
27
+ | `defaultEvents` | `WeekEvent[]` | `[]` | Initial events when uncontrolled. |
28
+ | `onEventsChange` | `(events: WeekEvent[]) => void` | | Every change: each drag frame, key press and agent action. |
29
+ | `onEventCommit` | `(event: WeekEvent, events: WeekEvent[]) => void` | | Once a move or resize ends (pointer up, key handled, agent action). Save here. |
30
+ | `onEventActivate` | `(event: WeekEvent) => void` | | Click without dragging, Enter or Space on an event — open its details. |
31
+ | `days` | `string[]` | `['Mon','Tue','Wed','Thu','Fri']` | Column labels, one column each. |
32
+ | `startHour` | `number` | `9` | First visible hour. |
33
+ | `endHour` | `number` | `17` | Hour the board ends at (exclusive). Events are clamped inside startHour–endHour. |
34
+ | `step` | `number` | `15` | Snap and arrow-key step in minutes; also the shortest event. |
35
+ | `hourHeight` | `number` | `60` | Pixels per hour row. |
36
+ | `hourFormat` | `'24h' \| '12h'` | | Controlled clock format. 24h shows "10:00–12:00"; 12h shows "10–12 PM". |
37
+ | `defaultHourFormat` | `'24h' \| '12h'` | `'24h'` | Initial clock format. |
38
+ | `onHourFormatChange` | `(format: '24h' \| '12h') => void` | | Clock switch changed. |
39
+ | `summary` | `boolean` | `true` | Show the big total of booked hours (away time is not counted). |
40
+ | `summaryLabel` | `string` | `'Hours booked'` | Mono label next to the total. |
41
+ | `clockToggle` | `boolean` | `true` | Show the 24h / 12h SegmentedControl in the footer. |
42
+ | `legend` | `boolean` | `true` | Show the meeting / focus / away legend in the footer. |
43
+ | `readOnly` | `boolean` | `false` | Events can be focused and activated but not moved or resized. |
44
+ | `radius` | `RadiusToken \| number` | `'lg'` | Frame squircle radius. |
45
+
46
+ ## Examples
47
+
48
+ ### Uncontrolled week, save on commit
49
+
50
+ ```tsx
51
+ <WeekSchedule
52
+ aria-label="This week"
53
+ defaultEvents={[
54
+ { id: 'standup', title: 'Standup', day: 0, start: 540, end: 570, kind: 'meeting' },
55
+ { id: 'focus', title: 'Focus time', day: 0, start: 600, end: 720, kind: 'focus' },
56
+ { id: 'flight', title: 'Flight to Berlin', day: 4, start: 840, end: 1020, kind: 'away' },
57
+ ]}
58
+ onEventCommit={(event, events) => save(events)}
59
+ />
60
+ ```
61
+
62
+ ### Controlled, 12h, Mon–Sun 8–20, no chrome
63
+
64
+ ```tsx
65
+ const [events, setEvents] = useState(initial)
66
+ <WeekSchedule
67
+ aria-label="Team week"
68
+ events={events}
69
+ onEventsChange={setEvents}
70
+ days={['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']}
71
+ startHour={8}
72
+ endHour={20}
73
+ step={30}
74
+ hourHeight={44}
75
+ defaultHourFormat="12h"
76
+ summary={false}
77
+ clockToggle={false}
78
+ legend={false}
79
+ />
80
+ ```
81
+
82
+ ### Read-only, custom total label
83
+
84
+ ```tsx
85
+ <WeekSchedule aria-label="My week" readOnly summaryLabel="Hours in meetings" events={events} onEventActivate={(e) => openEvent(e.id)} />
86
+ ```
87
+
88
+ ## Rules
89
+ - Give it an aria-label ("This week", "Team week"); it is a labelled group.
90
+ - The board has its own squircle frame — do not wrap it in a Card.
91
+ - Times are minutes from midnight in the API and "HH:MM" strings in agent state/actions; days are 0-based indexes into `days`.
92
+ - Use kind for meaning: meeting (outlined), focus (solid), away (hatched, not counted as booked). Do not recolour events.
93
+ - Save in onEventCommit, not onEventsChange (which fires on every drag frame).
94
+ - Keep it to one week (≤ 7 columns). It fits day columns to its container and shows Previous/Next days when the whole week cannot fit. Left/Right on an event moves it across days and follows it into the next range.
95
+
96
+ ## Accessibility
97
+ - Each event is a focusable role="button" with aria-roledescription="event" and an aria-label with its title, time, day and kind, plus how to move it.
98
+ - Keys on a focused event: ArrowUp/ArrowDown move by step, ArrowLeft/ArrowRight move a day, Shift+ArrowUp/ArrowDown shorten/lengthen it, Enter/Space activate, Escape cancels a drag.
99
+ - Every committed move is announced in a polite live region ("Review, Wed 11:15–12:15.").
100
+ - Kinds are told apart by shape (outline / fill / hatch) and the legend. Keyboard focus shows an inset ring. Editable events show a resize grip on hover or focus.
101
+ - Day and hour labels are decorative (aria-hidden) because every event label already names its day and time.
102
+
103
+ ## DOM contract (for agents operating the page)
104
+
105
+ - Selector: `[data-sw="week-schedule"]`
106
+ - `data-hour-format`: '24h' | '12h' on the root
107
+ - `data-dragging`: 'move' | 'resize' on the root and on the event being dragged
108
+ - `data-event-id / data-day / data-start / data-end / data-kind`: on each .sw-week-schedule__event (start/end as "HH:MM")
109
+ - `data-selected`: on the focused event
110
+ - `.sw-week-schedule__total[data-value]`: hours booked, e.g. "9.5"
111
+ - How to operate: Focus an event ([role="button"][aria-roledescription="event"]) and press arrow keys, or drag it / its bottom edge. Agent bridge: moveEvent(titleOrId, day (name or index), start "HH:MM"), resizeEvent(titleOrId, end "HH:MM"), setHourFormat("24h" | "12h"); state = { events: [{ id, title, day, dayIndex, start, end, kind }], hourFormat, hoursBooked, days, hours, step }.
112
+
113
+ Related: `calendar`, `time-input`, `timeline`, `segmented-control`