@cognitap/radiant 0.0.6 → 0.0.8

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 (196) hide show
  1. package/CHANGELOG.md +82 -395
  2. package/README.md +41 -1014
  3. package/RELEASE_POLICY.md +3 -3
  4. package/dist/library/Accordion.d.ts +3 -0
  5. package/dist/library/Accordion.d.ts.map +1 -1
  6. package/dist/library/Accordion.js +1 -1
  7. package/dist/library/Accordion.js.map +1 -1
  8. package/dist/library/Button.d.ts +5 -0
  9. package/dist/library/Button.d.ts.map +1 -1
  10. package/dist/library/Button.js +8 -7
  11. package/dist/library/Button.js.map +1 -1
  12. package/dist/library/Card.d.ts +2 -0
  13. package/dist/library/Card.d.ts.map +1 -1
  14. package/dist/library/Card.js +1 -1
  15. package/dist/library/Card.js.map +1 -1
  16. package/dist/library/Checkbox.d.ts +5 -0
  17. package/dist/library/Checkbox.d.ts.map +1 -1
  18. package/dist/library/Checkbox.js +3 -2
  19. package/dist/library/Checkbox.js.map +1 -1
  20. package/dist/library/Collapsible.d.ts +4 -0
  21. package/dist/library/Collapsible.d.ts.map +1 -1
  22. package/dist/library/Collapsible.js +22 -4
  23. package/dist/library/Collapsible.js.map +1 -1
  24. package/dist/library/Dialog.d.ts +3 -0
  25. package/dist/library/Dialog.d.ts.map +1 -1
  26. package/dist/library/Dialog.js.map +1 -1
  27. package/dist/library/Field.d.ts +8 -0
  28. package/dist/library/Field.d.ts.map +1 -1
  29. package/dist/library/Field.js +2 -0
  30. package/dist/library/Field.js.map +1 -1
  31. package/dist/library/Input.d.ts +3 -0
  32. package/dist/library/Input.d.ts.map +1 -1
  33. package/dist/library/Input.js +1 -0
  34. package/dist/library/Input.js.map +1 -1
  35. package/dist/library/Link.d.ts +5 -0
  36. package/dist/library/Link.d.ts.map +1 -1
  37. package/dist/library/Link.js.map +1 -1
  38. package/dist/library/RadioGroup.d.ts +8 -0
  39. package/dist/library/RadioGroup.d.ts.map +1 -1
  40. package/dist/library/RadioGroup.js +4 -2
  41. package/dist/library/RadioGroup.js.map +1 -1
  42. package/dist/library/Select.d.ts +87 -0
  43. package/dist/library/Select.d.ts.map +1 -0
  44. package/dist/library/Select.js +454 -0
  45. package/dist/library/Select.js.map +1 -0
  46. package/dist/library/cn.d.ts.map +1 -1
  47. package/dist/library/cn.js +20 -3
  48. package/dist/library/cn.js.map +1 -1
  49. package/dist/library/examples/expressive.d.ts +4 -0
  50. package/dist/library/examples/expressive.d.ts.map +1 -0
  51. package/dist/library/{themes → examples}/expressive.js +4 -3
  52. package/dist/library/examples/expressive.js.map +1 -0
  53. package/dist/library/examples/glass.d.ts +4 -0
  54. package/dist/library/examples/glass.d.ts.map +1 -0
  55. package/dist/library/{themes → examples}/glass.js +9 -3
  56. package/dist/library/examples/glass.js.map +1 -0
  57. package/dist/library/examples/index.d.ts +13 -0
  58. package/dist/library/examples/index.d.ts.map +1 -0
  59. package/dist/library/examples/index.js +32 -0
  60. package/dist/library/examples/index.js.map +1 -0
  61. package/dist/library/examples/jelly.d.ts +4 -0
  62. package/dist/library/examples/jelly.d.ts.map +1 -0
  63. package/dist/library/{themes → examples}/jelly.js +4 -3
  64. package/dist/library/examples/jelly.js.map +1 -0
  65. package/dist/library/examples/preset-values.d.ts.map +1 -0
  66. package/dist/library/examples/preset-values.js.map +1 -0
  67. package/dist/library/examples/radiant.d.ts +4 -0
  68. package/dist/library/examples/radiant.d.ts.map +1 -0
  69. package/dist/library/{themes → examples}/radiant.js +4 -3
  70. package/dist/library/examples/radiant.js.map +1 -0
  71. package/dist/library/examples/sharp-3d.d.ts +4 -0
  72. package/dist/library/examples/sharp-3d.d.ts.map +1 -0
  73. package/dist/library/{themes → examples}/sharp-3d.js +4 -3
  74. package/dist/library/examples/sharp-3d.js.map +1 -0
  75. package/dist/library/examples/soft-squircle.d.ts +4 -0
  76. package/dist/library/examples/soft-squircle.d.ts.map +1 -0
  77. package/dist/library/{themes → examples}/soft-squircle.js +4 -3
  78. package/dist/library/examples/soft-squircle.js.map +1 -0
  79. package/dist/library/examples/ticket.d.ts +4 -0
  80. package/dist/library/examples/ticket.d.ts.map +1 -0
  81. package/dist/library/{themes → examples}/ticket.js +4 -3
  82. package/dist/library/examples/ticket.js.map +1 -0
  83. package/dist/library/index.d.ts +3 -1
  84. package/dist/library/index.d.ts.map +1 -1
  85. package/dist/library/index.js +2 -1
  86. package/dist/library/index.js.map +1 -1
  87. package/dist/library/internal/select.d.ts +37 -0
  88. package/dist/library/internal/select.d.ts.map +1 -0
  89. package/dist/library/internal/select.js +42 -0
  90. package/dist/library/internal/select.js.map +1 -0
  91. package/dist/library/motion/MotionLink.d.ts +1 -0
  92. package/dist/library/motion/MotionLink.d.ts.map +1 -1
  93. package/dist/library/motion/MotionLink.js +9 -10
  94. package/dist/library/motion/MotionLink.js.map +1 -1
  95. package/dist/library/motion/host.d.ts +7 -3
  96. package/dist/library/motion/host.d.ts.map +1 -1
  97. package/dist/library/motion/host.js +13 -5
  98. package/dist/library/motion/host.js.map +1 -1
  99. package/dist/library/motion/popup.d.ts +5 -0
  100. package/dist/library/motion/popup.d.ts.map +1 -0
  101. package/dist/library/motion/popup.js +60 -0
  102. package/dist/library/motion/popup.js.map +1 -0
  103. package/dist/library/motion/press.d.ts.map +1 -1
  104. package/dist/library/motion/press.js +41 -14
  105. package/dist/library/motion/press.js.map +1 -1
  106. package/dist/library/motion/pressPolicy.d.ts.map +1 -1
  107. package/dist/library/motion/pressPolicy.js +2 -2
  108. package/dist/library/motion/pressPolicy.js.map +1 -1
  109. package/dist/library/motion/react.d.ts.map +1 -1
  110. package/dist/library/motion/react.js +3 -1
  111. package/dist/library/motion/react.js.map +1 -1
  112. package/dist/library/motion/transitions.d.ts.map +1 -1
  113. package/dist/library/motion/transitions.js +48 -15
  114. package/dist/library/motion/transitions.js.map +1 -1
  115. package/dist/library/react/useControllableState.d.ts +1 -0
  116. package/dist/library/react/useControllableState.d.ts.map +1 -1
  117. package/dist/library/react/useControllableState.js +8 -1
  118. package/dist/library/react/useControllableState.js.map +1 -1
  119. package/dist/library/selectStyles.d.ts +4 -0
  120. package/dist/library/selectStyles.d.ts.map +1 -0
  121. package/dist/library/selectStyles.js +32 -0
  122. package/dist/library/selectStyles.js.map +1 -0
  123. package/dist/library/styles.css +1 -1
  124. package/dist/library/themes/components.d.ts +24 -0
  125. package/dist/library/themes/components.d.ts.map +1 -1
  126. package/dist/library/themes/components.js +24 -0
  127. package/dist/library/themes/components.js.map +1 -1
  128. package/dist/library/themes/index.d.ts +1 -11
  129. package/dist/library/themes/index.d.ts.map +1 -1
  130. package/dist/library/themes/index.js +1 -19
  131. package/dist/library/themes/index.js.map +1 -1
  132. package/docs/accessibility.md +76 -142
  133. package/docs/architecture.md +208 -0
  134. package/docs/motion.md +115 -396
  135. package/docs/theming.md +275 -882
  136. package/package.json +9 -5
  137. package/src/Accordion.tsx +4 -1
  138. package/src/Button.tsx +13 -7
  139. package/src/Card.tsx +3 -1
  140. package/src/Checkbox.tsx +7 -2
  141. package/src/Collapsible.tsx +28 -4
  142. package/src/Dialog.tsx +3 -0
  143. package/src/Field.tsx +8 -0
  144. package/src/Input.tsx +3 -0
  145. package/src/Link.tsx +5 -0
  146. package/src/RadioGroup.tsx +10 -2
  147. package/src/Select.tsx +781 -0
  148. package/src/cn.ts +20 -3
  149. package/src/{themes → examples}/expressive.ts +5 -3
  150. package/src/{themes → examples}/glass.ts +10 -3
  151. package/src/examples/index.ts +35 -0
  152. package/src/{themes → examples}/jelly.ts +5 -3
  153. package/src/{themes → examples}/radiant.ts +5 -3
  154. package/src/{themes → examples}/sharp-3d.ts +5 -3
  155. package/src/{themes → examples}/soft-squircle.ts +5 -3
  156. package/src/{themes → examples}/ticket.ts +5 -3
  157. package/src/index.ts +28 -13
  158. package/src/internal/select.ts +80 -0
  159. package/src/motion/MotionLink.tsx +16 -11
  160. package/src/motion/host.ts +16 -7
  161. package/src/motion/popup.ts +55 -0
  162. package/src/motion/press.ts +32 -12
  163. package/src/motion/pressPolicy.ts +4 -2
  164. package/src/motion/react.ts +3 -1
  165. package/src/motion/transitions.ts +45 -14
  166. package/src/react/useControllableState.ts +7 -1
  167. package/src/selectStyles.ts +34 -0
  168. package/src/themes/components.ts +24 -0
  169. package/src/themes/index.ts +1 -22
  170. package/dist/library/themes/expressive.d.ts +0 -2
  171. package/dist/library/themes/expressive.d.ts.map +0 -1
  172. package/dist/library/themes/expressive.js.map +0 -1
  173. package/dist/library/themes/glass.d.ts +0 -2
  174. package/dist/library/themes/glass.d.ts.map +0 -1
  175. package/dist/library/themes/glass.js.map +0 -1
  176. package/dist/library/themes/jelly.d.ts +0 -2
  177. package/dist/library/themes/jelly.d.ts.map +0 -1
  178. package/dist/library/themes/jelly.js.map +0 -1
  179. package/dist/library/themes/preset-values.d.ts.map +0 -1
  180. package/dist/library/themes/preset-values.js.map +0 -1
  181. package/dist/library/themes/radiant.d.ts +0 -2
  182. package/dist/library/themes/radiant.d.ts.map +0 -1
  183. package/dist/library/themes/radiant.js.map +0 -1
  184. package/dist/library/themes/sharp-3d.d.ts +0 -2
  185. package/dist/library/themes/sharp-3d.d.ts.map +0 -1
  186. package/dist/library/themes/sharp-3d.js.map +0 -1
  187. package/dist/library/themes/soft-squircle.d.ts +0 -2
  188. package/dist/library/themes/soft-squircle.d.ts.map +0 -1
  189. package/dist/library/themes/soft-squircle.js.map +0 -1
  190. package/dist/library/themes/ticket.d.ts +0 -2
  191. package/dist/library/themes/ticket.d.ts.map +0 -1
  192. package/dist/library/themes/ticket.js.map +0 -1
  193. package/docs/system.md +0 -264
  194. /package/dist/library/{themes → examples}/preset-values.d.ts +0 -0
  195. /package/dist/library/{themes → examples}/preset-values.js +0 -0
  196. /package/src/{themes → examples}/preset-values.ts +0 -0
package/package.json CHANGED
@@ -1,8 +1,8 @@
1
1
  {
2
2
  "name": "@cognitap/radiant",
3
- "version": "0.0.6",
3
+ "version": "0.0.8",
4
4
  "description": "React interaction components and presentation primitives",
5
- "homepage": "https://github.com/cognitap/radiant#readme",
5
+ "homepage": "https://radiant-docs.pages.dev",
6
6
  "bugs": {
7
7
  "url": "https://github.com/cognitap/radiant/issues"
8
8
  },
@@ -15,7 +15,7 @@
15
15
  "LICENSE",
16
16
  "CHANGELOG.md",
17
17
  "RELEASE_POLICY.md",
18
- "docs/system.md",
18
+ "docs/architecture.md",
19
19
  "docs/motion.md",
20
20
  "docs/accessibility.md",
21
21
  "docs/theming.md",
@@ -48,6 +48,10 @@
48
48
  "types": "./dist/library/typography/index.d.ts",
49
49
  "default": "./dist/library/typography/index.js"
50
50
  },
51
+ "./examples": {
52
+ "types": "./dist/library/examples/index.d.ts",
53
+ "default": "./dist/library/examples/index.js"
54
+ },
51
55
  "./motion": {
52
56
  "types": "./dist/library/motion/index.d.ts",
53
57
  "default": "./dist/library/motion/index.js"
@@ -119,8 +123,8 @@
119
123
  "watch:js": "tsc -p tsconfig.build.json --watch --preserveWatchOutput",
120
124
  "watch:styles": "pnpm theme:generate && tailwindcss -i styles/library.css -o dist/library/styles.css --watch=always",
121
125
  "build:storybook": "pnpm theme:generate && storybook build --output-dir dist/storybook --disable-telemetry",
122
- "test": "pnpm build && node --test tests/*.test.mjs && node scripts/verify-package.mjs",
123
- "test:package": "pnpm build && node scripts/verify-package.mjs",
126
+ "test": "pnpm build && node --test tests/*.test.mjs && node scripts/verify-package.mjs --hydration",
127
+ "test:package": "pnpm build && node scripts/verify-package.mjs --hydration",
124
128
  "typecheck": "tsc --noEmit && pnpm typecheck:contracts",
125
129
  "typecheck:contracts": "tsc -p docs/contracts/tsconfig.json",
126
130
  "lint": "oxlint --deny-warnings",
package/src/Accordion.tsx CHANGED
@@ -16,7 +16,7 @@ import type {
16
16
  } from './Collapsible.js'
17
17
 
18
18
  const accordionClass =
19
- 'grid w-full gap-[var(--rad-accordion-gap,var(--rad-spacing-group-gap,0.75rem))]'
19
+ 'grid w-full min-w-0 gap-[var(--rad-accordion-gap,var(--rad-spacing-group-gap,0.75rem))]'
20
20
  const triggerClass =
21
21
  'in-[[data-slot~=field][data-disabled]]:[--_rad-disabled-opacity:1] data-disabled:cursor-not-allowed data-disabled:opacity-[var(--_rad-disabled-opacity,var(--rad-state-disabled-opacity,0.5))] forced-colors:data-disabled:opacity-100'
22
22
  const headingClass = 'm-0 min-w-0 break-words [font:inherit]'
@@ -56,6 +56,7 @@ type AccordionMultipleProps = AccordionBaseProps &
56
56
 
57
57
  export type AccordionProps = AccordionSingleProps | AccordionMultipleProps
58
58
 
59
+ /** Stable, distinct value within this owner. Selection and native name belong to Accordion. */
59
60
  export type AccordionItemProps = Omit<
60
61
  CollapsibleProps,
61
62
  'open' | 'defaultOpen' | 'onOpenChange' | 'name'
@@ -65,6 +66,7 @@ export type AccordionItemProps = Omit<
65
66
  }
66
67
 
67
68
  export type AccordionTriggerProps = CollapsibleTriggerProps & {
69
+ /** Heading inside the native summary; null leaves heading composition to the caller. */
68
70
  level?: AccordionHeadingLevel | null
69
71
  }
70
72
 
@@ -76,6 +78,7 @@ export type AccordionState = {
76
78
  type: 'single' | 'multiple'
77
79
  value: AccordionValue
78
80
  disabled: boolean
81
+ /** Request selection; a controlled owner may decline. Root disabled guards requests. */
79
82
  setItemOpen: (value: string, open: boolean) => void
80
83
  }
81
84
 
package/src/Button.tsx CHANGED
@@ -27,11 +27,16 @@ export type ButtonProps = Omit<ComponentProps<'button'>, 'style'> & {
27
27
  'data-slot'?: string
28
28
  /** Forward resolved presentation, children, native attributes and ref to one button host. */
29
29
  render?: (props: ButtonRenderProps) => ReactElement
30
+ /** Visual treatment; native submission behavior stays on type. */
30
31
  variant?: ButtonVariant
32
+ /** Semantic action palette, independent of treatment. */
31
33
  tone?: Tone
34
+ /** Shared action dimensions; defaults to medium. */
32
35
  controlSize?: ControlSize
36
+ /** Square action; supply an accessible name for icon-only children. */
33
37
  iconOnly?: boolean
34
38
  fullWidth?: boolean
39
+ /** Block activation and show progress while preserving focus and the label. */
35
40
  pending?: boolean
36
41
  /** Requires MotionProvider. Off also suppresses legacy spatial transitions. */
37
42
  motion?: 'inherit' | 'off'
@@ -55,7 +60,8 @@ export function Button({
55
60
  }: ButtonProps) {
56
61
  const callerOwnsScale = callerOwnsPress(props.style, className)
57
62
  const press = usePressHost(ref, motion === 'off' || callerOwnsScale)
58
- const spatial = (press.active || motion === 'off') && !callerOwnsScale
63
+ const motionOff = motion === 'off' || press.off
64
+ const spatial = (press.active || motionOff) && !callerOwnsScale
59
65
  const buttonProps: ButtonRenderProps = {
60
66
  ...props,
61
67
  ref: press.active ? press.ref : ref,
@@ -65,19 +71,19 @@ export function Button({
65
71
  },
66
72
  onPointerUp: event => {
67
73
  props.onPointerUp?.(event)
68
- press.release()
74
+ press.release(event.nativeEvent)
69
75
  },
70
76
  onPointerCancel: event => {
71
77
  props.onPointerCancel?.(event)
72
- press.release()
78
+ press.release(event.nativeEvent)
73
79
  },
74
80
  onPointerLeave: event => {
75
81
  props.onPointerLeave?.(event)
76
- press.release()
82
+ press.release(event.nativeEvent)
77
83
  },
78
84
  onLostPointerCapture: event => {
79
85
  props.onLostPointerCapture?.(event)
80
- press.release()
86
+ press.release(event.nativeEvent)
81
87
  },
82
88
  onBlur: event => {
83
89
  props.onBlur?.(event)
@@ -89,7 +95,7 @@ export function Button({
89
95
  },
90
96
  onKeyUp: event => {
91
97
  props.onKeyUp?.(event)
92
- press.release()
98
+ press.release(event.nativeEvent)
93
99
  },
94
100
  type,
95
101
  'aria-busy': pending || props['aria-busy'],
@@ -100,7 +106,7 @@ export function Button({
100
106
  className: cn(
101
107
  actionVariants({ variant, tone, controlSize, iconOnly, fullWidth }),
102
108
  spatial && springPressClass,
103
- motion === 'off' && !callerOwnsScale && offPressClass,
109
+ motionOff && !callerOwnsScale && offPressClass,
104
110
  className
105
111
  ),
106
112
  onClick: composeAction(
package/src/Card.tsx CHANGED
@@ -10,7 +10,7 @@ const colorMotionClass =
10
10
  const cardVariants = cva([
11
11
  colorMotionClass,
12
12
  'font-[family-name:var(--rad-typography-roles-ui-body-family,system-ui,sans-serif)] tracking-[var(--rad-typography-roles-ui-body-letter-spacing,-0.011em)] text-[length:var(--rad-typography-roles-ui-body-size,0.875rem)] font-[number:var(--rad-typography-roles-ui-body-weight,400)] leading-[var(--rad-typography-roles-ui-body-line-height,1.5)]',
13
- 'box-border grid w-full gap-[var(--rad-card-gap,var(--rad-surface-gap,1rem))] text-start antialiased',
13
+ 'box-border grid w-full min-w-0 gap-[var(--rad-card-gap,var(--rad-surface-gap,1rem))] text-start antialiased',
14
14
  'rounded-[var(--rad-card-radius,var(--rad-surface-radius,0.75rem))]',
15
15
  '[corner-shape:var(--rad-card-corner-shape,var(--rad-surface-corner-shape,round))]',
16
16
  '[border-width:var(--rad-card-border-width,var(--rad-surface-border-width,1px))]',
@@ -67,11 +67,13 @@ type CardPartProps<Host extends 'div' | 'h2' | 'p'> = Omit<ComponentProps<Host>,
67
67
  'data-slot'?: string
68
68
  }
69
69
 
70
+ /** Passive div host. Compose native actions, form state and dedicated motion wrappers explicitly. */
70
71
  export type CardProps = CardPartProps<'div'>
71
72
 
72
73
  export type CardHeaderProps = CardPartProps<'div'>
73
74
 
74
75
  export type CardTitleProps = CardPartProps<'h2'> & {
76
+ /** Semantic heading host; choose a level that fits the surrounding page outline. */
75
77
  level?: CardHeadingLevel
76
78
  }
77
79
 
package/src/Checkbox.tsx CHANGED
@@ -43,19 +43,23 @@ const markClass =
43
43
  'pointer-events-none absolute inset-0 size-full scale-65 [color:var(--rad-checkbox-mark,var(--rad-color-accent-foreground,oklch(0.985_0_0)))] peer-disabled:[color:var(--rad-checkbox-mark,var(--rad-color-muted-foreground,oklch(0.45_0.01_286)))] forced-colors:text-[HighlightText] forced-colors:peer-disabled:text-[GrayText]'
44
44
 
45
45
  const rowClass =
46
- 'inline-flex min-h-6 cursor-pointer items-center gap-[var(--rad-checkbox-gap,var(--rad-spacing-label-gap,0.5rem))] select-none has-disabled:cursor-not-allowed'
46
+ 'inline-flex min-h-6 min-w-0 max-w-full cursor-pointer items-center gap-[var(--rad-checkbox-gap,var(--rad-spacing-label-gap,0.5rem))] select-none has-disabled:cursor-not-allowed'
47
47
 
48
48
  const labelClass =
49
- 'font-[family-name:var(--rad-typography-roles-ui-label-family,system-ui,sans-serif)] tracking-[var(--rad-typography-roles-ui-label-letter-spacing,-0.011em)] font-[number:var(--rad-typography-roles-ui-label-weight,400)] [color:var(--rad-checkbox-label-color,var(--rad-color-foreground,oklch(0.21_0.006_286)))] text-[length:var(--rad-checkbox-label-size,var(--_rad-control-font-size))] leading-[var(--rad-typography-roles-ui-label-line-height,1.4)]'
49
+ 'min-w-0 break-words font-[family-name:var(--rad-typography-roles-ui-label-family,system-ui,sans-serif)] tracking-[var(--rad-typography-roles-ui-label-letter-spacing,-0.011em)] font-[number:var(--rad-typography-roles-ui-label-weight,400)] [color:var(--rad-checkbox-label-color,var(--rad-color-foreground,oklch(0.21_0.006_286)))] text-[length:var(--rad-checkbox-label-size,var(--_rad-control-font-size))] leading-[var(--rad-typography-roles-ui-label-line-height,1.4)]'
50
50
 
51
51
  export type CheckboxProps = Omit<
52
52
  ComponentProps<'input'>,
53
53
  'type' | 'checked' | 'defaultChecked' | 'style'
54
54
  > &
55
55
  CheckedOwner & {
56
+ /** Convenience label; omit it when Field supplies the single control's label. */
56
57
  label?: ReactNode
58
+ /** Native mixed presentation, independent of checked and the submitted value. */
57
59
  indeterminate?: boolean
60
+ /** Shared visual metrics, matching Input and RadioGroup. */
58
61
  controlSize?: ControlSize
62
+ /** Input styles. Parts style the wrapper, label and decorative indicators. */
59
63
  style?: ThemeStyle
60
64
  parts?: ControlParts
61
65
  }
@@ -64,6 +68,7 @@ function hasContent(value: ReactNode) {
64
68
  return value != null && value !== false && value !== ''
65
69
  }
66
70
 
71
+ /** Native selection and form behavior. Read event.target.checked for state, value for data. */
67
72
  export function Checkbox({
68
73
  className,
69
74
  controlSize = 'medium',
@@ -1,13 +1,14 @@
1
1
  'use client'
2
2
 
3
3
  import type { ComponentProps, ToggleEvent } from 'react'
4
- import { createContext, useContext, useId } from 'react'
4
+ import { createContext, useContext, useId, useLayoutEffect, useRef } from 'react'
5
5
  import { cva } from 'class-variance-authority'
6
6
  import { useTransitionHost } from './motion/host.js'
7
7
  import { cn } from './cn.js'
8
8
  import { joinIds } from './internal/ids.js'
9
9
  import type { ThemeStyle } from './themes/defineTheme.js'
10
10
  import { useControllableState } from './react/useControllableState.js'
11
+ import { useComposedRefs } from './react/useComposedRefs.js'
11
12
 
12
13
  const colorMotionClass =
13
14
  'transition-colors duration-[var(--rad-motion-color-duration,150ms)] motion-reduce:transition-none'
@@ -68,8 +69,10 @@ const collapsibleContentVariants = cva([
68
69
  export type CollapsibleProps = Omit<ComponentProps<'details'>, 'open' | 'onToggle' | 'style'> &
69
70
  ({ open: boolean; defaultOpen?: never } | { open?: undefined; defaultOpen?: boolean }) & {
70
71
  style?: ThemeStyle
72
+ /** Height/marker presentation only. Native disclosure state never waits for motion. */
71
73
  motion?: 'inherit' | 'off'
72
74
  'data-slot'?: string
75
+ /** Use this to write controlled state; onToggle remains a native observation. */
73
76
  onOpenChange?: (open: boolean) => void
74
77
  onToggle?: (event: ToggleEvent<HTMLDetailsElement>) => void
75
78
  }
@@ -80,11 +83,13 @@ export type CollapsibleState = {
80
83
  setOpen: (open: boolean) => void
81
84
  }
82
85
 
86
+ /** One direct-child native summary. Keep buttons and links in Content. */
83
87
  export type CollapsibleTriggerProps = Omit<ComponentProps<'summary'>, 'style'> & {
84
88
  style?: ThemeStyle
85
89
  'data-slot'?: string
86
90
  }
87
91
 
92
+ /** Native div host; keep content in normal flow for natural-height measurement. */
88
93
  export type CollapsibleContentProps = Omit<ComponentProps<'div'>, 'style'> & {
89
94
  style?: ThemeStyle
90
95
  'data-slot'?: string
@@ -113,8 +118,15 @@ export function Collapsible({
113
118
  children,
114
119
  ...props
115
120
  }: CollapsibleProps) {
116
- const transition = useTransitionHost<HTMLDetailsElement>('disclosure', ref, motion === 'off')
121
+ const node = useRef<HTMLDetailsElement>(null)
122
+ const nativeRef = useComposedRefs(node, ref)
123
+ const transition = useTransitionHost<HTMLDetailsElement>(
124
+ 'disclosure',
125
+ nativeRef,
126
+ motion === 'off'
127
+ )
117
128
  const contentId = useId()
129
+ const motionOff = motion === 'off' || transition.off
118
130
  const {
119
131
  value: isOpen,
120
132
  request: setOpen,
@@ -126,17 +138,29 @@ export function Collapsible({
126
138
  initialValue: false,
127
139
  onChange: onOpenChange
128
140
  })
141
+ const reconciled = useRef<HTMLDetailsElement | null>(null)
142
+ useLayoutEffect(() => {
143
+ const host = node.current
144
+ if (!host || reconciled.current === host) return
145
+ reconciled.current = host
146
+ // A native toggle may have completed before React installed its listener.
147
+ // Adoption is one local change; restoring a controlled owner is not a request.
148
+ if (controlled) host.open = isOpen
149
+ else setOpen(host.open)
150
+ }, [controlled, isOpen, setOpen])
129
151
 
130
152
  return (
131
153
  <CollapsibleContext.Provider value={{ open: isOpen, contentId, setOpen }}>
132
154
  <details
133
155
  {...props}
134
- ref={transition.active ? transition.ref : ref}
156
+ ref={transition.active ? transition.ref : nativeRef}
157
+ suppressHydrationWarning
135
158
  className={cn(
136
159
  collapsibleVariants(),
137
160
  transition.active &&
161
+ transition.ready &&
138
162
  '[&::details-content]:[content-visibility:visible] [&::details-content]:transition-none [&:not([open])::details-content]:h-[var(--_rad-spring-details-height,0px)] open:[&::details-content]:h-[var(--_rad-spring-details-height,auto)]',
139
- motion === 'off' && '[&::details-content]:transition-none',
163
+ motionOff && '[&::details-content]:transition-none [&>summary>svg]:transition-none',
140
164
  className
141
165
  )}
142
166
  data-slot={joinIds('collapsible', props['data-slot'])}
package/src/Dialog.tsx CHANGED
@@ -67,6 +67,7 @@ export type DialogProps = (
67
67
  | { open: boolean; defaultOpen?: never }
68
68
  | { open?: undefined; defaultOpen?: boolean }
69
69
  ) & {
70
+ /** A change request. The controlled owner may decline it; prop syncs do not notify. */
70
71
  onOpenChange?: (open: boolean) => void
71
72
  /** `true` calls `showModal()`. `false` calls `show()` and leaves the rest of the page active. */
72
73
  modal?: boolean
@@ -91,10 +92,12 @@ export type DialogState = {
91
92
 
92
93
  export type DialogRenderProps = ButtonRenderProps
93
94
 
95
+ /** Button props/render/ref contract, with protected dialog relationships. */
94
96
  export type DialogTriggerProps = ButtonProps
95
97
 
96
98
  export type DialogContentProps = Omit<ComponentProps<'dialog'>, 'open' | 'style'> & {
97
99
  style?: ThemeStyle
100
+ /** Opt-in MotionProvider presentation; native close and focus never wait for an exit. */
98
101
  motion?: 'inherit' | 'off'
99
102
  }
100
103
 
package/src/Field.tsx CHANGED
@@ -43,6 +43,7 @@ const requiredClass =
43
43
 
44
44
  export type FieldLayout = 'control' | 'group'
45
45
 
46
+ /** Forward every prop to one native control; merge any external description IDs. */
46
47
  export type FieldControlProps = {
47
48
  id: string
48
49
  required?: boolean
@@ -68,13 +69,16 @@ export type FieldState = {
68
69
  type FieldOwn = {
69
70
  /** Additional identities; Field always retains its base identity. */
70
71
  'data-slot'?: string
72
+ /** The control label, or the group's native legend. */
71
73
  label: ReactNode
72
74
  description?: ReactNode
75
+ /** Consumer-owned validation content. Present errors immediately mark the owner invalid. */
73
76
  error?: ReactNode
74
77
  required?: boolean
75
78
  disabled?: boolean
76
79
  requiredIndicator?: ReactNode
77
80
  style?: ThemeStyle
81
+ /** Presentation only; Field keeps each part's IDs, ARIA and native semantics. */
78
82
  parts?: {
79
83
  label?: PartStyle
80
84
  description?: PartStyle
@@ -88,7 +92,9 @@ type FieldControl = FieldOwn &
88
92
  layout?: 'control'
89
93
  form?: never
90
94
  name?: never
95
+ /** The input's ID. Root id/ref still target Field's div. */
91
96
  controlId?: string
97
+ /** Radiant controls connect automatically; native adapters forward the callback props. */
92
98
  children?: ReactNode | ((control: FieldControlProps) => ReactNode)
93
99
  }
94
100
 
@@ -103,6 +109,7 @@ export type FieldProps = FieldControl | FieldGroup
103
109
 
104
110
  const FieldContext = createContext<FieldState | null>(null)
105
111
 
112
+ /** Nearest Field metadata, or null. Groups have no single target: controlProps is null. */
106
113
  export function useField(): FieldState | null {
107
114
  return useContext(FieldContext)
108
115
  }
@@ -144,6 +151,7 @@ function definedProps(props: FieldControlProps): FieldControlProps {
144
151
  ) as FieldControlProps
145
152
  }
146
153
 
154
+ /** Owns label/help/error relationships; the consumer owns values, validation and focus. */
147
155
  export function Field(props: FieldProps) {
148
156
  const {
149
157
  label,
package/src/Input.tsx CHANGED
@@ -41,10 +41,13 @@ const inputVariants = cva([
41
41
 
42
42
  export type InputProps = Omit<ComponentProps<'input'>, 'value' | 'defaultValue' | 'style'> &
43
43
  ValueOwner<Exclude<ComponentProps<'input'>['value'], undefined>> & {
44
+ /** Shared visual metrics. Native size remains a numeric character-width hint. */
44
45
  controlSize?: ControlSize
46
+ /** Applied to the native input, including caller-owned motion styles. */
45
47
  style?: ThemeStyle
46
48
  }
47
49
 
50
+ /** Native editing, selection, events and ref; Field supplies owned form relationships. */
48
51
  export function Input({
49
52
  className,
50
53
  controlSize = 'medium',
package/src/Link.tsx CHANGED
@@ -42,10 +42,15 @@ export type LinkRenderProps = Omit<ComponentProps<'a'>, 'style'> & {
42
42
 
43
43
  export type LinkProps = Omit<ComponentProps<'a'>, 'style'> & {
44
44
  style?: ThemeStyle
45
+ /** Inline/subtle inherit text metrics; action treatments share Button's presentation. */
45
46
  variant?: LinkVariant
47
+ /** Semantic palette, independent of treatment. */
46
48
  tone?: Tone
49
+ /** Shared action dimensions; inline/subtle keep their surrounding text size. */
47
50
  controlSize?: ControlSize
51
+ /** Default target to _blank and rel to noopener noreferrer; explicit native values win. */
48
52
  external?: boolean
53
+ /** Forward every resolved prop, ref and child to one native or router anchor. */
49
54
  render?: (props: LinkRenderProps) => ReactElement
50
55
  }
51
56
 
@@ -44,10 +44,10 @@ const dotClass =
44
44
  'pointer-events-none absolute inset-[30%] rounded-[var(--rad-radio-radius,999px)] bg-[var(--rad-radio-mark,var(--rad-color-accent-foreground,oklch(0.985_0_0)))] peer-disabled:bg-[var(--rad-radio-mark,var(--rad-color-muted-foreground,oklch(0.45_0.01_286)))] opacity-0 peer-checked:opacity-100 forced-colors:bg-[HighlightText] forced-colors:peer-disabled:bg-[GrayText]'
45
45
 
46
46
  const rowClass =
47
- 'inline-flex min-h-6 cursor-pointer items-center gap-[var(--rad-radio-label-gap,var(--rad-spacing-label-gap,0.5rem))] select-none has-disabled:cursor-not-allowed'
47
+ 'inline-flex min-h-6 min-w-0 max-w-full cursor-pointer items-center gap-[var(--rad-radio-label-gap,var(--rad-spacing-label-gap,0.5rem))] select-none has-disabled:cursor-not-allowed'
48
48
 
49
49
  const labelClass =
50
- 'font-[family-name:var(--rad-typography-roles-ui-label-family,system-ui,sans-serif)] tracking-[var(--rad-typography-roles-ui-label-letter-spacing,-0.011em)] font-[number:var(--rad-typography-roles-ui-label-weight,400)] [color:var(--rad-radio-label-color,var(--rad-color-foreground,oklch(0.21_0.006_286)))] text-[length:var(--rad-radio-label-size,var(--_rad-control-font-size))] leading-[var(--rad-typography-roles-ui-label-line-height,1.4)]'
50
+ 'min-w-0 break-words font-[family-name:var(--rad-typography-roles-ui-label-family,system-ui,sans-serif)] tracking-[var(--rad-typography-roles-ui-label-letter-spacing,-0.011em)] font-[number:var(--rad-typography-roles-ui-label-weight,400)] [color:var(--rad-radio-label-color,var(--rad-color-foreground,oklch(0.21_0.006_286)))] text-[length:var(--rad-radio-label-size,var(--_rad-control-font-size))] leading-[var(--rad-typography-roles-ui-label-line-height,1.4)]'
51
51
 
52
52
  const optionsClass =
53
53
  'grid justify-items-start gap-[var(--rad-radio-group-gap,var(--rad-spacing-group-gap,0.75rem))]'
@@ -70,10 +70,13 @@ export type RadioGroupProps = Omit<
70
70
  'layout' | 'children' | 'onChange' | 'defaultValue' | 'parts'
71
71
  > &
72
72
  ValueOwner<string | null> & {
73
+ /** Stable native group name. Options supply distinct string values, including ''. */
73
74
  name: string
75
+ /** Shared Input/Checkbox/Radio metrics; each option may override them. */
74
76
  controlSize?: ControlSize
75
77
  parts?: NonNullable<FieldProps['parts']> & { options?: PartStyle }
76
78
  onChange?: (event: ChangeEvent<HTMLInputElement>) => void
79
+ /** Receives the selected string. Use this or onChange to write state, not both. */
77
80
  onValueChange?: (value: string) => void
78
81
  children?: ReactNode
79
82
  }
@@ -83,10 +86,13 @@ export type RadioProps = Omit<
83
86
  'type' | 'value' | 'checked' | 'defaultChecked' | 'style'
84
87
  > &
85
88
  CheckedOwner & {
89
+ /** Convenience label. Without it, provide an accessible name on the native input. */
86
90
  label?: ReactNode
91
+ /** Submitted data, independent of standalone checked/defaultChecked ownership. */
87
92
  value: string
88
93
  controlSize?: ControlSize
89
94
  style?: ThemeStyle
95
+ /** Presentation only. Root styling, native props and ref still reach the input. */
90
96
  parts?: ControlParts
91
97
  }
92
98
 
@@ -94,6 +100,7 @@ function hasContent(value: ReactNode) {
94
100
  return value != null && value !== false && value !== ''
95
101
  }
96
102
 
103
+ /** Native fieldset: owns option name and selection; controlled form reset belongs to the caller. */
97
104
  export function RadioGroup({
98
105
  name,
99
106
  value,
@@ -142,6 +149,7 @@ export function RadioGroup({
142
149
  )
143
150
  }
144
151
 
152
+ /** Native radio. Inside RadioGroup, omit checked/defaultChecked and conflicting names. */
145
153
  export function Radio({
146
154
  className,
147
155
  controlSize: controlSizeProp,