@appss/ui 0.0.0-stage → 0.2.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 (317) hide show
  1. package/AGENTS.md +41 -0
  2. package/README.md +262 -2
  3. package/dist/appearances/profiles.d.ts +4 -0
  4. package/dist/appearances/profiles.d.ts.map +1 -0
  5. package/dist/appearances/profiles.js +5 -0
  6. package/dist/appearances/profiles.js.map +1 -0
  7. package/dist/appearances/reddit/profile.d.ts +187 -0
  8. package/dist/appearances/reddit/profile.d.ts.map +1 -0
  9. package/dist/appearances/reddit/profile.js +107 -0
  10. package/dist/appearances/reddit/profile.js.map +1 -0
  11. package/dist/appearances/reddit/reddit.module.css.js +240 -0
  12. package/dist/appearances/reddit/reddit.module.css.js.map +1 -0
  13. package/dist/appearances/telegram/profile.d.ts +197 -0
  14. package/dist/appearances/telegram/profile.d.ts.map +1 -0
  15. package/dist/appearances/telegram/profile.js +114 -0
  16. package/dist/appearances/telegram/profile.js.map +1 -0
  17. package/dist/appearances/telegram/telegram.module.css.js +270 -0
  18. package/dist/appearances/telegram/telegram.module.css.js.map +1 -0
  19. package/dist/components/Accordion/Accordion.d.ts +4 -0
  20. package/dist/components/Accordion/Accordion.d.ts.map +1 -0
  21. package/dist/components/Accordion/Accordion.js +91 -0
  22. package/dist/components/Accordion/Accordion.js.map +1 -0
  23. package/dist/components/Accordion/Accordion.module.css.js +30 -0
  24. package/dist/components/Accordion/Accordion.module.css.js.map +1 -0
  25. package/dist/components/Accordion/Accordion.types.d.ts +34 -0
  26. package/dist/components/Accordion/Accordion.types.d.ts.map +1 -0
  27. package/dist/components/Avatar/Avatar.d.ts +4 -0
  28. package/dist/components/Avatar/Avatar.d.ts.map +1 -0
  29. package/dist/components/Avatar/Avatar.js +50 -0
  30. package/dist/components/Avatar/Avatar.js.map +1 -0
  31. package/dist/components/Avatar/Avatar.module.css.js +18 -0
  32. package/dist/components/Avatar/Avatar.module.css.js.map +1 -0
  33. package/dist/components/Avatar/Avatar.types.d.ts +24 -0
  34. package/dist/components/Avatar/Avatar.types.d.ts.map +1 -0
  35. package/dist/components/Banner/Banner.d.ts +3 -0
  36. package/dist/components/Banner/Banner.d.ts.map +1 -0
  37. package/dist/components/Banner/Banner.js +39 -0
  38. package/dist/components/Banner/Banner.js.map +1 -0
  39. package/dist/components/Banner/Banner.module.css.js +24 -0
  40. package/dist/components/Banner/Banner.module.css.js.map +1 -0
  41. package/dist/components/Banner/Banner.types.d.ts +25 -0
  42. package/dist/components/Banner/Banner.types.d.ts.map +1 -0
  43. package/dist/components/BottomNav/BottomNav.d.ts +3 -0
  44. package/dist/components/BottomNav/BottomNav.d.ts.map +1 -0
  45. package/dist/components/BottomNav/BottomNav.js +68 -0
  46. package/dist/components/BottomNav/BottomNav.js.map +1 -0
  47. package/dist/components/BottomNav/BottomNav.module.css.js +24 -0
  48. package/dist/components/BottomNav/BottomNav.module.css.js.map +1 -0
  49. package/dist/components/BottomNav/BottomNav.types.d.ts +35 -0
  50. package/dist/components/BottomNav/BottomNav.types.d.ts.map +1 -0
  51. package/dist/components/Button/Button.d.ts +3 -0
  52. package/dist/components/Button/Button.d.ts.map +1 -0
  53. package/dist/components/Button/Button.js +52 -0
  54. package/dist/components/Button/Button.js.map +1 -0
  55. package/dist/components/Button/Button.module.css.js +24 -0
  56. package/dist/components/Button/Button.module.css.js.map +1 -0
  57. package/dist/components/Button/Button.types.d.ts +23 -0
  58. package/dist/components/Button/Button.types.d.ts.map +1 -0
  59. package/dist/components/Card/Card.d.ts +3 -0
  60. package/dist/components/Card/Card.d.ts.map +1 -0
  61. package/dist/components/Card/Card.js +50 -0
  62. package/dist/components/Card/Card.js.map +1 -0
  63. package/dist/components/Card/Card.module.css.js +21 -0
  64. package/dist/components/Card/Card.module.css.js.map +1 -0
  65. package/dist/components/Card/Card.types.d.ts +23 -0
  66. package/dist/components/Card/Card.types.d.ts.map +1 -0
  67. package/dist/components/ChatListItem/ChatListItem.d.ts +7 -0
  68. package/dist/components/ChatListItem/ChatListItem.d.ts.map +1 -0
  69. package/dist/components/ChatListItem/ChatListItem.js +75 -0
  70. package/dist/components/ChatListItem/ChatListItem.js.map +1 -0
  71. package/dist/components/ChatListItem/ChatListItem.module.css.js +51 -0
  72. package/dist/components/ChatListItem/ChatListItem.module.css.js.map +1 -0
  73. package/dist/components/ChatListItem/ChatListItem.types.d.ts +38 -0
  74. package/dist/components/ChatListItem/ChatListItem.types.d.ts.map +1 -0
  75. package/dist/components/ChatListItem/MessageStatusIcon.d.ts +7 -0
  76. package/dist/components/ChatListItem/MessageStatusIcon.d.ts.map +1 -0
  77. package/dist/components/ChatListItem/MessageStatusIcon.js +18 -0
  78. package/dist/components/ChatListItem/MessageStatusIcon.js.map +1 -0
  79. package/dist/components/Dialog/Dialog.d.ts +4 -0
  80. package/dist/components/Dialog/Dialog.d.ts.map +1 -0
  81. package/dist/components/Dialog/Dialog.js +63 -0
  82. package/dist/components/Dialog/Dialog.js.map +1 -0
  83. package/dist/components/Dialog/Dialog.module.css.js +21 -0
  84. package/dist/components/Dialog/Dialog.module.css.js.map +1 -0
  85. package/dist/components/Dialog/Dialog.types.d.ts +26 -0
  86. package/dist/components/Dialog/Dialog.types.d.ts.map +1 -0
  87. package/dist/components/Divider/Divider.d.ts +3 -0
  88. package/dist/components/Divider/Divider.d.ts.map +1 -0
  89. package/dist/components/Divider/Divider.js +27 -0
  90. package/dist/components/Divider/Divider.js.map +1 -0
  91. package/dist/components/Divider/Divider.module.css.js +9 -0
  92. package/dist/components/Divider/Divider.module.css.js.map +1 -0
  93. package/dist/components/Divider/Divider.types.d.ts +17 -0
  94. package/dist/components/Divider/Divider.types.d.ts.map +1 -0
  95. package/dist/components/IconButton/IconButton.d.ts +3 -0
  96. package/dist/components/IconButton/IconButton.d.ts.map +1 -0
  97. package/dist/components/IconButton/IconButton.js +49 -0
  98. package/dist/components/IconButton/IconButton.js.map +1 -0
  99. package/dist/components/IconButton/IconButton.module.css.js +15 -0
  100. package/dist/components/IconButton/IconButton.module.css.js.map +1 -0
  101. package/dist/components/IconButton/IconButton.types.d.ts +25 -0
  102. package/dist/components/IconButton/IconButton.types.d.ts.map +1 -0
  103. package/dist/components/Likes/Likes.d.ts +4 -0
  104. package/dist/components/Likes/Likes.d.ts.map +1 -0
  105. package/dist/components/Likes/Likes.js +85 -0
  106. package/dist/components/Likes/Likes.js.map +1 -0
  107. package/dist/components/Likes/Likes.module.css.js +18 -0
  108. package/dist/components/Likes/Likes.module.css.js.map +1 -0
  109. package/dist/components/Likes/Likes.types.d.ts +27 -0
  110. package/dist/components/Likes/Likes.types.d.ts.map +1 -0
  111. package/dist/components/Link/Link.d.ts +3 -0
  112. package/dist/components/Link/Link.d.ts.map +1 -0
  113. package/dist/components/Link/Link.js +47 -0
  114. package/dist/components/Link/Link.js.map +1 -0
  115. package/dist/components/Link/Link.module.css.js +15 -0
  116. package/dist/components/Link/Link.module.css.js.map +1 -0
  117. package/dist/components/Link/Link.types.d.ts +22 -0
  118. package/dist/components/Link/Link.types.d.ts.map +1 -0
  119. package/dist/components/Menu/Menu.d.ts +4 -0
  120. package/dist/components/Menu/Menu.d.ts.map +1 -0
  121. package/dist/components/Menu/Menu.js +134 -0
  122. package/dist/components/Menu/Menu.js.map +1 -0
  123. package/dist/components/Menu/Menu.module.css.js +27 -0
  124. package/dist/components/Menu/Menu.module.css.js.map +1 -0
  125. package/dist/components/Menu/Menu.types.d.ts +32 -0
  126. package/dist/components/Menu/Menu.types.d.ts.map +1 -0
  127. package/dist/components/MessageBubble/MessageBubble.d.ts +3 -0
  128. package/dist/components/MessageBubble/MessageBubble.d.ts.map +1 -0
  129. package/dist/components/MessageBubble/MessageBubble.js +85 -0
  130. package/dist/components/MessageBubble/MessageBubble.js.map +1 -0
  131. package/dist/components/MessageBubble/MessageBubble.module.css.js +54 -0
  132. package/dist/components/MessageBubble/MessageBubble.module.css.js.map +1 -0
  133. package/dist/components/MessageBubble/MessageBubble.types.d.ts +54 -0
  134. package/dist/components/MessageBubble/MessageBubble.types.d.ts.map +1 -0
  135. package/dist/components/MessageComposer/MessageComposer.d.ts +3 -0
  136. package/dist/components/MessageComposer/MessageComposer.d.ts.map +1 -0
  137. package/dist/components/MessageComposer/MessageComposer.js +55 -0
  138. package/dist/components/MessageComposer/MessageComposer.js.map +1 -0
  139. package/dist/components/MessageComposer/MessageComposer.module.css.js +24 -0
  140. package/dist/components/MessageComposer/MessageComposer.module.css.js.map +1 -0
  141. package/dist/components/MessageComposer/MessageComposer.types.d.ts +27 -0
  142. package/dist/components/MessageComposer/MessageComposer.types.d.ts.map +1 -0
  143. package/dist/components/MessageDivider/MessageDivider.d.ts +3 -0
  144. package/dist/components/MessageDivider/MessageDivider.d.ts.map +1 -0
  145. package/dist/components/MessageDivider/MessageDivider.js +28 -0
  146. package/dist/components/MessageDivider/MessageDivider.js.map +1 -0
  147. package/dist/components/MessageDivider/MessageDivider.module.css.js +12 -0
  148. package/dist/components/MessageDivider/MessageDivider.module.css.js.map +1 -0
  149. package/dist/components/MessageDivider/MessageDivider.types.d.ts +19 -0
  150. package/dist/components/MessageDivider/MessageDivider.types.d.ts.map +1 -0
  151. package/dist/components/NavBar/NavBar.d.ts +3 -0
  152. package/dist/components/NavBar/NavBar.d.ts.map +1 -0
  153. package/dist/components/NavBar/NavBar.js +42 -0
  154. package/dist/components/NavBar/NavBar.js.map +1 -0
  155. package/dist/components/NavBar/NavBar.module.css.js +24 -0
  156. package/dist/components/NavBar/NavBar.module.css.js.map +1 -0
  157. package/dist/components/NavBar/NavBar.types.d.ts +26 -0
  158. package/dist/components/NavBar/NavBar.types.d.ts.map +1 -0
  159. package/dist/components/NavList/NavList.d.ts +3 -0
  160. package/dist/components/NavList/NavList.d.ts.map +1 -0
  161. package/dist/components/NavList/NavList.js +53 -0
  162. package/dist/components/NavList/NavList.js.map +1 -0
  163. package/dist/components/NavList/NavList.module.css.js +24 -0
  164. package/dist/components/NavList/NavList.module.css.js.map +1 -0
  165. package/dist/components/NavList/NavList.types.d.ts +31 -0
  166. package/dist/components/NavList/NavList.types.d.ts.map +1 -0
  167. package/dist/components/SearchField/SearchField.d.ts +3 -0
  168. package/dist/components/SearchField/SearchField.d.ts.map +1 -0
  169. package/dist/components/SearchField/SearchField.js +38 -0
  170. package/dist/components/SearchField/SearchField.js.map +1 -0
  171. package/dist/components/SearchField/SearchField.module.css.js +18 -0
  172. package/dist/components/SearchField/SearchField.module.css.js.map +1 -0
  173. package/dist/components/SearchField/SearchField.types.d.ts +23 -0
  174. package/dist/components/SearchField/SearchField.types.d.ts.map +1 -0
  175. package/dist/components/Section/Section.d.ts +4 -0
  176. package/dist/components/Section/Section.d.ts.map +1 -0
  177. package/dist/components/Section/Section.js +101 -0
  178. package/dist/components/Section/Section.js.map +1 -0
  179. package/dist/components/Section/Section.module.css.js +36 -0
  180. package/dist/components/Section/Section.module.css.js.map +1 -0
  181. package/dist/components/Section/Section.types.d.ts +36 -0
  182. package/dist/components/Section/Section.types.d.ts.map +1 -0
  183. package/dist/components/Stat/Stat.d.ts +4 -0
  184. package/dist/components/Stat/Stat.d.ts.map +1 -0
  185. package/dist/components/Stat/Stat.js +31 -0
  186. package/dist/components/Stat/Stat.js.map +1 -0
  187. package/dist/components/Stat/Stat.module.css.js +15 -0
  188. package/dist/components/Stat/Stat.module.css.js.map +1 -0
  189. package/dist/components/Stat/Stat.types.d.ts +18 -0
  190. package/dist/components/Stat/Stat.types.d.ts.map +1 -0
  191. package/dist/components/Switch/Switch.d.ts +4 -0
  192. package/dist/components/Switch/Switch.d.ts.map +1 -0
  193. package/dist/components/Switch/Switch.js +45 -0
  194. package/dist/components/Switch/Switch.js.map +1 -0
  195. package/dist/components/Switch/Switch.module.css.js +21 -0
  196. package/dist/components/Switch/Switch.module.css.js.map +1 -0
  197. package/dist/components/Switch/Switch.types.d.ts +19 -0
  198. package/dist/components/Switch/Switch.types.d.ts.map +1 -0
  199. package/dist/components/Tabs/Tabs.d.ts +4 -0
  200. package/dist/components/Tabs/Tabs.d.ts.map +1 -0
  201. package/dist/components/Tabs/Tabs.js +92 -0
  202. package/dist/components/Tabs/Tabs.js.map +1 -0
  203. package/dist/components/Tabs/Tabs.module.css.js +24 -0
  204. package/dist/components/Tabs/Tabs.module.css.js.map +1 -0
  205. package/dist/components/Tabs/Tabs.types.d.ts +31 -0
  206. package/dist/components/Tabs/Tabs.types.d.ts.map +1 -0
  207. package/dist/components/Tag/Tag.d.ts +3 -0
  208. package/dist/components/Tag/Tag.d.ts.map +1 -0
  209. package/dist/components/Tag/Tag.js +33 -0
  210. package/dist/components/Tag/Tag.js.map +1 -0
  211. package/dist/components/Tag/Tag.module.css.js +12 -0
  212. package/dist/components/Tag/Tag.module.css.js.map +1 -0
  213. package/dist/components/Tag/Tag.types.d.ts +20 -0
  214. package/dist/components/Tag/Tag.types.d.ts.map +1 -0
  215. package/dist/components/Tooltip/Tooltip.d.ts +4 -0
  216. package/dist/components/Tooltip/Tooltip.d.ts.map +1 -0
  217. package/dist/components/Tooltip/Tooltip.js +63 -0
  218. package/dist/components/Tooltip/Tooltip.js.map +1 -0
  219. package/dist/components/Tooltip/Tooltip.module.css.js +12 -0
  220. package/dist/components/Tooltip/Tooltip.module.css.js.map +1 -0
  221. package/dist/components/Tooltip/Tooltip.types.d.ts +24 -0
  222. package/dist/components/Tooltip/Tooltip.types.d.ts.map +1 -0
  223. package/dist/core/AppssProvider.d.ts +21 -0
  224. package/dist/core/AppssProvider.d.ts.map +1 -0
  225. package/dist/core/AppssProvider.js +42 -0
  226. package/dist/core/AppssProvider.js.map +1 -0
  227. package/dist/core/appearance.d.ts +28 -0
  228. package/dist/core/appearance.d.ts.map +1 -0
  229. package/dist/core/appearance.js +40 -0
  230. package/dist/core/appearance.js.map +1 -0
  231. package/dist/core/host.d.ts +28 -0
  232. package/dist/core/host.d.ts.map +1 -0
  233. package/dist/core/host.js +42 -0
  234. package/dist/core/host.js.map +1 -0
  235. package/dist/hosts/adapters.d.ts +5 -0
  236. package/dist/hosts/adapters.d.ts.map +1 -0
  237. package/dist/hosts/adapters.js +21 -0
  238. package/dist/hosts/adapters.js.map +1 -0
  239. package/dist/icons/icons.d.ts +164 -0
  240. package/dist/icons/icons.d.ts.map +1 -0
  241. package/dist/icons/icons.js +220 -0
  242. package/dist/icons/icons.js.map +1 -0
  243. package/dist/icons/index.d.ts +2 -0
  244. package/dist/icons/index.d.ts.map +1 -0
  245. package/dist/icons/index.js +43 -0
  246. package/dist/icons/index.js.map +1 -0
  247. package/dist/index.d.ts +58 -0
  248. package/dist/index.d.ts.map +1 -0
  249. package/dist/index.js +62 -0
  250. package/dist/index.js.map +1 -0
  251. package/dist/integrations.d.ts +9 -0
  252. package/dist/integrations.d.ts.map +1 -0
  253. package/dist/integrations.js +27 -0
  254. package/dist/integrations.js.map +1 -0
  255. package/dist/modules/hideOnScroll.d.ts +7 -0
  256. package/dist/modules/hideOnScroll.d.ts.map +1 -0
  257. package/dist/modules/hideOnScroll.js +39 -0
  258. package/dist/modules/hideOnScroll.js.map +1 -0
  259. package/dist/modules/index.d.ts +2 -0
  260. package/dist/modules/index.d.ts.map +1 -0
  261. package/dist/modules/index.js +5 -0
  262. package/dist/modules/index.js.map +1 -0
  263. package/dist/recipes/buttons.d.ts +30 -0
  264. package/dist/recipes/buttons.d.ts.map +1 -0
  265. package/dist/recipes/buttons.js +28 -0
  266. package/dist/recipes/buttons.js.map +1 -0
  267. package/dist/recipes/index.d.ts +4 -0
  268. package/dist/recipes/index.d.ts.map +1 -0
  269. package/dist/recipes/index.js +23 -0
  270. package/dist/recipes/index.js.map +1 -0
  271. package/dist/recipes/navigation.d.ts +36 -0
  272. package/dist/recipes/navigation.d.ts.map +1 -0
  273. package/dist/recipes/navigation.js +28 -0
  274. package/dist/recipes/navigation.js.map +1 -0
  275. package/dist/recipes/recipes.module.css.js +27 -0
  276. package/dist/recipes/recipes.module.css.js.map +1 -0
  277. package/dist/recipes/whatsapp.d.ts +155 -0
  278. package/dist/recipes/whatsapp.d.ts.map +1 -0
  279. package/dist/recipes/whatsapp.js +155 -0
  280. package/dist/recipes/whatsapp.js.map +1 -0
  281. package/dist/recipes/whatsapp.module.css.js +135 -0
  282. package/dist/recipes/whatsapp.module.css.js.map +1 -0
  283. package/dist/styles.css +4157 -0
  284. package/docs/components/Accordion.md +76 -0
  285. package/docs/components/Avatar.md +64 -0
  286. package/docs/components/Banner.md +70 -0
  287. package/docs/components/BottomNav.md +86 -0
  288. package/docs/components/Button.md +93 -0
  289. package/docs/components/Card.md +75 -0
  290. package/docs/components/Cell.md +89 -0
  291. package/docs/components/ChatListItem.md +102 -0
  292. package/docs/components/Dialog.md +93 -0
  293. package/docs/components/Divider.md +66 -0
  294. package/docs/components/IconButton.md +86 -0
  295. package/docs/components/Likes.md +74 -0
  296. package/docs/components/Link.md +79 -0
  297. package/docs/components/Menu.md +105 -0
  298. package/docs/components/MessageBubble.md +91 -0
  299. package/docs/components/MessageComposer.md +93 -0
  300. package/docs/components/MessageDivider.md +66 -0
  301. package/docs/components/NavBar.md +85 -0
  302. package/docs/components/NavList.md +85 -0
  303. package/docs/components/SearchField.md +81 -0
  304. package/docs/components/Section.md +81 -0
  305. package/docs/components/Stat.md +66 -0
  306. package/docs/components/Switch.md +74 -0
  307. package/docs/components/Tabs.md +85 -0
  308. package/docs/components/Tag.md +63 -0
  309. package/docs/components/Tooltip.md +62 -0
  310. package/docs/exports.json +90 -0
  311. package/docs/foundations.md +99 -0
  312. package/docs/gaps.json +12 -0
  313. package/docs/icons.md +20 -0
  314. package/docs/index.md +57 -0
  315. package/docs/recipes.md +43 -0
  316. package/docs/replaces.json +12 -0
  317. package/package.json +81 -4
@@ -0,0 +1,93 @@
1
+ # MessageComposer
2
+
3
+ The message input bar at the bottom of a chat: an optional leading action (attach), a text field with an inline action, and trailing actions (microphone, send). `label` is required. Enter calls `onSend`; you control the value.
4
+
5
+ Import `MessageComposer` from `@appss/ui`.
6
+
7
+ ## When to use
8
+
9
+ - The bottom of a chat, support or AI assistant screen.
10
+ - A single-line prompt with a send button.
11
+ - Not for search: use `SearchField`.
12
+ - Not for form fields or multi-line notes: write a text field or textarea (gap).
13
+
14
+ ## Props
15
+
16
+ | Prop | Type | Default | Notes |
17
+ | ------------- | ----------------- | -------- | ---------------------------------------------------------- |
18
+ | `label` | `string` | required | Accessible name, e.g. "Message". |
19
+ | `value` | `string` | | Native; control it. |
20
+ | `onChange` | `(event) => void` | | Native: read `event.currentTarget.value`. |
21
+ | `onSend` | `() => void` | | Called on Enter. Call the same handler from a send button. |
22
+ | `placeholder` | `string` | | Native. |
23
+ | `leading` | `ReactNode` | | Before the field, e.g. an attach IconButton. |
24
+ | `fieldAction` | `ReactNode` | | Inside the field at the end, e.g. a sticker IconButton. |
25
+ | `trailing` | `ReactNode` | | After the field: microphone, camera or a send IconButton. |
26
+
27
+ Also `appearance`, `recipe`, `adaptation`, `className`, `style` and native `<input>` attributes except `type`, `size` and `aria-label` (use `label`).
28
+
29
+ Placement is the app's job: keep it at the bottom of the chat column (sticky or the last row of a flex column).
30
+
31
+ ## Slots
32
+
33
+ `root`, `leading`, `field`, `input`, `fieldAction`, `trailing`.
34
+
35
+ ## Sizes by platform
36
+
37
+ | Platform | Look |
38
+ | -------- | -------------------------------------------------------------------------------------- |
39
+ | Web | field 40, pill |
40
+ | Telegram | no background, glass field 44; use IconButton `variant="soft"` for glass round buttons |
41
+ | Reddit | field 40, pill |
42
+
43
+ ## Recipes
44
+
45
+ `whatsappComposer`: beige bar, white capsule field 40 with a grey border, text 17.
46
+
47
+ ## Correct
48
+
49
+ ```tsx
50
+ import { useState } from "react";
51
+ import { AttachIcon, MicIcon } from "@appss/ui/icons";
52
+
53
+ export function ChatInput({ onSend }: { onSend: (text: string) => void }) {
54
+ const [text, setText] = useState("");
55
+ const send = () => {
56
+ if (!text.trim()) return;
57
+ onSend(text.trim());
58
+ setText("");
59
+ };
60
+ return (
61
+ <MessageComposer
62
+ label="Message"
63
+ placeholder="Message"
64
+ value={text}
65
+ onChange={(event) => setText(event.currentTarget.value)}
66
+ onSend={send}
67
+ leading={<IconButton label="Attach file" icon={<AttachIcon />} variant="soft" />}
68
+ trailing={
69
+ text ? (
70
+ <Button size="sm" onClick={send}>
71
+ Send
72
+ </Button>
73
+ ) : (
74
+ <IconButton label="Record voice message" icon={<MicIcon />} variant="soft" />
75
+ )
76
+ }
77
+ />
78
+ );
79
+ }
80
+ ```
81
+
82
+ ## Wrong
83
+
84
+ ```tsx
85
+ // Hand-made bar: no accessible name, hard-coded colours, Enter not handled.
86
+ <div style={{ display: "flex", background: "#f4f4f5" }}>
87
+ <input placeholder="Message" value={text} onChange={(e) => setText(e.target.value)} />
88
+ <button style={{ background: "#2481cc" }} onClick={send}>Send</button>
89
+ </div>
90
+
91
+ // Invented props: onSubmit and onChangeText do not exist; label is missing.
92
+ <MessageComposer onSubmit={send} onChangeText={setText} />
93
+ ```
@@ -0,0 +1,66 @@
1
+ # MessageDivider
2
+
3
+ A marker inside a message list: a date chip (`variant="date"`) or the "N unread messages" bar (`variant="unread"`).
4
+
5
+ Import `MessageDivider` from `@appss/ui`.
6
+
7
+ ## When to use
8
+
9
+ - Between message groups of different days: "Today", "Monday, 12 May".
10
+ - Before the first unread message: `variant="unread"`.
11
+ - Not for separating content blocks: use `Divider`.
12
+ - Not for section titles: use `Section` `header` or a heading.
13
+
14
+ ## Props
15
+
16
+ | Prop | Type | Default | Notes |
17
+ | --------- | -------------------- | -------- | -------------------------------- |
18
+ | `label` | `string` | required | The text; there are no children. |
19
+ | `variant` | `"date" \| "unread"` | `"date"` | |
20
+
21
+ Also `appearance`, `recipe`, `adaptation`, `className`, `style` and native `<div>` attributes except `children`.
22
+
23
+ ## Slots
24
+
25
+ `root`, `label`.
26
+
27
+ ## Sizes by platform
28
+
29
+ | Platform | Look |
30
+ | -------- | ------------------------------------- |
31
+ | Web | 13 px pill chip |
32
+ | Telegram | dark translucent chip with white text |
33
+ | Reddit | 13 px pill chip |
34
+
35
+ ## Recipes
36
+
37
+ `whatsappMessageDivider`: white 14/600 chip with a light shadow; translucent white unread bar.
38
+
39
+ ## Correct
40
+
41
+ ```tsx
42
+ export function ThreadStart() {
43
+ return (
44
+ <>
45
+ <MessageDivider label="Yesterday" />
46
+ <MessageBubble direction="in" time="18:02">
47
+ Your order has shipped.
48
+ </MessageBubble>
49
+ <MessageDivider variant="unread" label="2 unread messages" />
50
+ <MessageBubble direction="in" time="08:15">
51
+ The courier will arrive between 10:00 and 12:00.
52
+ </MessageBubble>
53
+ </>
54
+ );
55
+ }
56
+ ```
57
+
58
+ ## Wrong
59
+
60
+ ```tsx
61
+ // Hand-made chip with hard-coded colours.
62
+ <div style={{ textAlign: "center", fontSize: 12, color: "#999" }}>Yesterday</div>
63
+
64
+ // Children instead of label.
65
+ <MessageDivider>Yesterday</MessageDivider>
66
+ ```
@@ -0,0 +1,85 @@
1
+ # NavBar
2
+
3
+ Screen header: title and subtitle, a leading slot (back button, logo), trailing actions, or any content in the center (for example a SearchField).
4
+
5
+ Import `NavBar` from `@appss/ui`.
6
+
7
+ ## When to use
8
+
9
+ - The top of every screen.
10
+ - A back button in `leading`, up to three `IconButton`s or a `Menu` in `trailing`.
11
+ - A chat header: `title` = name, `subtitle` = status, `trailing` = Avatar.
12
+ - An iOS-style large title on root screens: `titleSize="large"`.
13
+ - A search screen: put a `SearchField` as `children`, it renders in the center.
14
+ - Not for headings inside content: use `Card` `title` or `Section` `header`.
15
+ - Not for a marketing hero: use `Banner` or your own layout.
16
+
17
+ ## Props
18
+
19
+ | Prop | Type | Default | Notes |
20
+ | ----------- | ----------------------- | ----------- | ----------------------------------------------------------- |
21
+ | `title` | `ReactNode` | | |
22
+ | `subtitle` | `ReactNode` | | Second line: status, date, counter. |
23
+ | `leading` | `ReactNode` | | Back button or logo. |
24
+ | `trailing` | `ReactNode` | | Icon actions, a Menu or an Avatar. |
25
+ | `children` | `ReactNode` | | Rendered in the center under the title, e.g. a SearchField. |
26
+ | `align` | `"start" \| "center"` | `"start"` | Telegram always centers. |
27
+ | `titleSize` | `"regular" \| "large"` | `"regular"` | `large`: actions on the first row, a big title below. |
28
+ | `titleAs` | `"h1" \| "h2" \| "div"` | `"h1"` | Heading level of the title. |
29
+
30
+ Also `appearance`, `recipe`, `adaptation`, `className`, `style` and native `<header>` attributes except `title`. There is no `left`, `right`, `onBack` or `backButton` prop: use `leading`, `trailing` and an IconButton.
31
+
32
+ ## Slots
33
+
34
+ `root`, `leading`, `center`, `title`, `subtitle`, `trailing`.
35
+
36
+ ## Sizes by platform
37
+
38
+ | Platform | Height | Look |
39
+ | -------- | ------ | ----------------------------------------------------------------------------------- |
40
+ | Web | 56 | title 17/700, large title 32 |
41
+ | Telegram | 64 | transparent, glass buttons, title with subtitle in a glass capsule, always centered |
42
+ | Reddit | 56 | white with a bottom line |
43
+
44
+ ## Recipes
45
+
46
+ `whatsappHeader`: height 64, translucent blurred background; with `titleSize="large"` transparent with a 34/800 title.
47
+
48
+ ## Correct
49
+
50
+ ```tsx
51
+ import { BackIcon } from "@appss/ui/icons";
52
+
53
+ export function OrderHeader() {
54
+ return (
55
+ <NavBar
56
+ title="Order 1042"
57
+ subtitle="Arrives Thursday"
58
+ align="center"
59
+ leading={<IconButton label="Back" icon={<BackIcon />} onClick={() => history.back()} />}
60
+ trailing={
61
+ <Menu
62
+ trigger="Help"
63
+ items={[
64
+ { id: "contact", label: "Contact support" },
65
+ { id: "cancel", label: "Cancel order", tone: "destructive", separatorBefore: true },
66
+ ]}
67
+ />
68
+ }
69
+ />
70
+ );
71
+ }
72
+ ```
73
+
74
+ ## Wrong
75
+
76
+ ```tsx
77
+ // Raw header with hard-coded colours: ignores the Telegram theme and safe areas.
78
+ <header style={{ display: "flex", background: "#ffffff", borderBottom: "1px solid #eee" }}>
79
+ <button onClick={back}>←</button>
80
+ <h1>Order</h1>
81
+ </header>
82
+
83
+ // Invented props.
84
+ <NavBar title="Order" onBack={back} right={<MoreIcon />} />
85
+ ```
@@ -0,0 +1,85 @@
1
+ # NavList
2
+
3
+ Navigation as a list of links: a vertical sidebar or a horizontal site header menu.
4
+
5
+ Import `NavList` from `@appss/ui`.
6
+
7
+ ## When to use
8
+
9
+ - Site and desktop navigation: a sidebar (`orientation="vertical"`) or a header menu (`orientation="horizontal"`, usually inside `NavBar`).
10
+ - Grouped sidebars: one NavList per group inside an `Accordion variant="section"`.
11
+ - Not for a mobile tab bar: use `BottomNav`.
12
+ - Not for settings rows with values or switches: use `Section` and `Cell`.
13
+
14
+ ## Props
15
+
16
+ | Prop | Type | Default | Notes |
17
+ | ------------- | ------------------------------------------------- | ------------ | ---------------------------------------------- |
18
+ | `items` | `{ id, label, href, icon?, badge?, disabled? }[]` | required | `icon` can be an icon or an Avatar. |
19
+ | `activeId` | `string` | | Omit when no item matches the current page. |
20
+ | `onNavigate` | `(id, event) => void` | | Call `event.preventDefault()` for SPA routing. |
21
+ | `orientation` | `"vertical" \| "horizontal"` | `"vertical"` | |
22
+ | `aria-label` | `string` | | Name the navigation, e.g. "Documentation". |
23
+
24
+ Also `appearance`, `recipe`, `adaptation`, `className`, `style` and native `<nav>` attributes.
25
+
26
+ ## Slots
27
+
28
+ `root`, `list`, `item`, `icon`, `label`, `badge`.
29
+
30
+ ## Sizes by platform
31
+
32
+ | Platform | Item height | Look |
33
+ | -------- | ----------- | ----------------------------------------------------------------- |
34
+ | Web | 40 | radius 10; horizontal items have no background, active underlined |
35
+ | Telegram | 44 | theme colours |
36
+ | Reddit | 40 | radius 8 |
37
+
38
+ ## Recipes
39
+
40
+ None.
41
+
42
+ ## Correct
43
+
44
+ ```tsx
45
+ import { useState } from "react";
46
+
47
+ const pages = [
48
+ { id: "overview", label: "Overview", href: "/" },
49
+ { id: "pricing", label: "Pricing", href: "/pricing" },
50
+ { id: "help", label: "Help center", href: "/help" },
51
+ ];
52
+
53
+ export function SiteHeader() {
54
+ const [page, setPage] = useState("overview");
55
+ return (
56
+ <NavBar leading={<strong>Linden Studio</strong>}>
57
+ <NavList
58
+ aria-label="Site"
59
+ orientation="horizontal"
60
+ items={pages}
61
+ activeId={page}
62
+ onNavigate={(id, event) => {
63
+ event.preventDefault();
64
+ setPage(id);
65
+ }}
66
+ />
67
+ </NavBar>
68
+ );
69
+ }
70
+ ```
71
+
72
+ ## Wrong
73
+
74
+ ```tsx
75
+ // Raw list of links with a hard-coded active colour and no aria-current.
76
+ <nav>
77
+ <ul>
78
+ <li><a href="/" style={{ color: "#6554d9", fontWeight: 700 }}>Overview</a></li>
79
+ <li><a href="/pricing">Pricing</a></li>
80
+ </ul>
81
+ </nav>
82
+
83
+ // BottomNav on desktop, or invented props on NavList.
84
+ <NavList links={pages} current="/" vertical />
85
+ ```
@@ -0,0 +1,81 @@
1
+ # SearchField
2
+
3
+ Search input with `role="search"`, a magnifier and an optional trailing action. `label` is required: the placeholder is not a label.
4
+
5
+ Import `SearchField` from `@appss/ui`.
6
+
7
+ ## When to use
8
+
9
+ - Searching or filtering a list by text: chats, products, places.
10
+ - In the `NavBar` center (`children`) on search-first screens.
11
+ - A scope chip or an "Ask" button on the right: `trailing`.
12
+ - Not for other text input (names, notes, amounts): write a text field (gap).
13
+ - Not for a chat input: use `MessageComposer`.
14
+
15
+ ## Props
16
+
17
+ | Prop | Type | Default | Notes |
18
+ | ------------- | ----------------------- | ---------- | ----------------------------------------- |
19
+ | `label` | `string` | required | Accessible name, e.g. "Search products". |
20
+ | `value` | `string` | | Native; control it with `onChange`. |
21
+ | `onChange` | `(event) => void` | | Native: read `event.currentTarget.value`. |
22
+ | `placeholder` | `string` | | Native hint text. |
23
+ | `leading` | `ReactNode` | magnifier | Replace the magnifier icon. |
24
+ | `trailing` | `ReactNode` | | Action on the right. |
25
+ | `variant` | `"filled" \| "outline"` | `"filled"` | |
26
+
27
+ Also `appearance`, `recipe`, `adaptation`, `className`, `style` and native `<input>` attributes except `type`, `size` and `aria-label` (use `label`). `className` and `style` go to the root, other attributes to the input.
28
+
29
+ ## Slots
30
+
31
+ `root`, `leading`, `input`, `trailing`.
32
+
33
+ ## Sizes by platform
34
+
35
+ | Platform | Height | Look |
36
+ | -------- | ------ | -------------------------------------------------------------- |
37
+ | Web | 40 | pill |
38
+ | Telegram | 44 | grey capsule; icon and hint centered while empty and unfocused |
39
+ | Reddit | 40 | `outline` has an orange-yellow gradient border |
40
+
41
+ ## Recipes
42
+
43
+ None.
44
+
45
+ ## Correct
46
+
47
+ ```tsx
48
+ import { useState } from "react";
49
+
50
+ const products = ["Oat milk latte", "Cold brew", "Matcha tonic", "Flat white"];
51
+
52
+ export function ProductSearch() {
53
+ const [query, setQuery] = useState("");
54
+ const found = products.filter((name) => name.toLowerCase().includes(query.toLowerCase()));
55
+ return (
56
+ <>
57
+ <SearchField
58
+ label="Search drinks"
59
+ placeholder="Search"
60
+ value={query}
61
+ onChange={(event) => setQuery(event.currentTarget.value)}
62
+ />
63
+ <Section>
64
+ {found.map((name) => (
65
+ <Cell key={name} title={name} />
66
+ ))}
67
+ </Section>
68
+ </>
69
+ );
70
+ }
71
+ ```
72
+
73
+ ## Wrong
74
+
75
+ ```tsx
76
+ // Raw input: placeholder only, no label, hard-coded colours.
77
+ <input type="search" placeholder="Search" style={{ background: "#f1f1f4", border: "none" }} />
78
+
79
+ // onChange does not receive the string, and label is missing (TypeScript error).
80
+ <SearchField placeholder="Search" onChange={(text) => setQuery(text)} />
81
+ ```
@@ -0,0 +1,81 @@
1
+ # Section
2
+
3
+ A grouped list block: an optional header, a body of `Cell` rows, an optional footer. The building block of settings, profiles, order summaries and any list of rows.
4
+
5
+ Import `Section` from `@appss/ui`.
6
+
7
+ ## When to use
8
+
9
+ - Settings and profile screens: several Sections, each with a few Cells.
10
+ - Lists of entries: habits, orders, time slots, transactions.
11
+ - A group title (`header`) and an explanation under the group (`footer`).
12
+ - Not for free-form content (text, images, charts): use `Card`.
13
+ - Not for conversations: use `ChatListItem`.
14
+
15
+ ## Props
16
+
17
+ | Prop | Type | Default | Notes |
18
+ | ---------- | ----------- | ------- | --------------------------------------------- |
19
+ | `header` | `ReactNode` | | Group title, rendered as an `h2`. |
20
+ | `footer` | `ReactNode` | | Explanation under the group, rendered as `p`. |
21
+ | `children` | `ReactNode` | | `Cell` rows. |
22
+
23
+ Also `appearance`, `recipe`, `adaptation`, `className`, `style` and native `<section>` attributes except `title`.
24
+
25
+ ## Slots
26
+
27
+ `root`, `header`, `body`, `footer`.
28
+
29
+ ## Sizes by platform
30
+
31
+ | Platform | Look |
32
+ | -------- | ------------------------------------------------ |
33
+ | Web | group radius 16 with a border, rows 52 |
34
+ | Telegram | radius 12, rows 44, 17 px text, inset separators |
35
+ | Reddit | radius 16, rows 48 |
36
+
37
+ ## Recipes
38
+
39
+ `whatsappSection`: white groups with radius 26 on a grey page, 13 px grey captions. Pair it with `whatsappCell`.
40
+
41
+ ## Correct
42
+
43
+ ```tsx
44
+ import { useState } from "react";
45
+ import { ChevronRightIcon, LockIcon, NotificationIcon } from "@appss/ui/icons";
46
+
47
+ export function PrivacySettings() {
48
+ const [reminders, setReminders] = useState(true);
49
+ return (
50
+ <Section header="Notifications" footer="Reminders arrive at the time you set for each habit.">
51
+ <Cell
52
+ title="Daily reminders"
53
+ before={<NotificationIcon />}
54
+ after={
55
+ <Switch aria-label="Daily reminders" checked={reminders} onCheckedChange={setReminders} />
56
+ }
57
+ />
58
+ <Cell
59
+ title="Privacy"
60
+ subtitle="Who can see your progress"
61
+ before={<LockIcon />}
62
+ after={<ChevronRightIcon />}
63
+ href="/settings/privacy"
64
+ />
65
+ </Section>
66
+ );
67
+ }
68
+ ```
69
+
70
+ ## Wrong
71
+
72
+ ```tsx
73
+ // Hand-made group: hard-coded white background breaks dark and Telegram themes.
74
+ <div style={{ background: "#fff", borderRadius: 12, padding: 16 }}>
75
+ <h3>Notifications</h3>
76
+ <div className="row">Daily reminders <input type="checkbox" /></div>
77
+ </div>
78
+
79
+ // Invented props: Section has header and footer, not title or items.
80
+ <Section title="Notifications" items={rows} />
81
+ ```
@@ -0,0 +1,66 @@
1
+ # Stat
2
+
3
+ A big value with a caption under it: "12 day streak", "$240 spent", "1,204 points".
4
+
5
+ Import `Stat` from `@appss/ui`.
6
+
7
+ ## When to use
8
+
9
+ - Totals, streaks, scores and prices at the top of a dashboard or profile.
10
+ - A row of 2-4 key numbers inside a `Card` (lay them out with a grid).
11
+ - Not for a value at the end of a list row: use `Cell` `after`.
12
+ - Not for charts or progress bars: write them yourself (gap).
13
+
14
+ ## Props
15
+
16
+ | Prop | Type | Default | Notes |
17
+ | ------- | ----------- | -------- | ------------------------------ |
18
+ | `value` | `ReactNode` | required | The number, already formatted. |
19
+ | `label` | `ReactNode` | required | Caption under the value. |
20
+
21
+ Also `appearance`, `recipe`, `adaptation`, `className`, `style` and native `<div>` attributes except `children`.
22
+
23
+ ## Slots
24
+
25
+ `root`, `value`, `label`.
26
+
27
+ ## Sizes by platform
28
+
29
+ | Platform | Value | Label |
30
+ | -------- | ------ | ----- |
31
+ | Web | 18/700 | 13 |
32
+ | Telegram | 18/700 | 13 |
33
+ | Reddit | 16/700 | 13 |
34
+
35
+ ## Recipes
36
+
37
+ None.
38
+
39
+ ## Correct
40
+
41
+ ```tsx
42
+ export function WeekSummary() {
43
+ return (
44
+ <Card title="This week">
45
+ <div style={{ display: "grid", gridTemplateColumns: "repeat(3, 1fr)", gap: 12 }}>
46
+ <Stat value="12" label="Day streak" />
47
+ <Stat value="86%" label="Completed" />
48
+ <Stat value="4" label="Habits" />
49
+ </div>
50
+ </Card>
51
+ );
52
+ }
53
+ ```
54
+
55
+ ## Wrong
56
+
57
+ ```tsx
58
+ // Raw markup with hard-coded sizes and colours.
59
+ <div>
60
+ <div style={{ fontSize: 24, fontWeight: 700, color: "#111" }}>12</div>
61
+ <div style={{ color: "#888" }}>Day streak</div>
62
+ </div>
63
+
64
+ // Invented props.
65
+ <Stat title="Day streak" number={12} trend="up" />
66
+ ```
@@ -0,0 +1,74 @@
1
+ # Switch
2
+
3
+ On/off toggle: a native checkbox with `role="switch"`. Needs a visible label (`children`) or an `aria-label`.
4
+
5
+ Import `Switch` from `@appss/ui`.
6
+
7
+ ## When to use
8
+
9
+ - Settings that apply immediately: reminders, dark mode, public profile.
10
+ - Usually in a static `Cell`'s `after`, with `aria-label` repeating the Cell title.
11
+ - Not for choosing one of several options: use `Tabs variant="segmented"`.
12
+ - Not for checklists or "I agree" boxes: write a checkbox (gap).
13
+
14
+ ## Props
15
+
16
+ | Prop | Type | Default | Notes |
17
+ | ----------------- | ---------------------------- | ------- | ---------------------------------------------- |
18
+ | `checked` | `boolean` | | Controlled state; pair with `onCheckedChange`. |
19
+ | `defaultChecked` | `boolean` | | Uncontrolled initial state. |
20
+ | `onCheckedChange` | `(checked: boolean) => void` | | Receives the new boolean. |
21
+ | `children` | `ReactNode` | | Visible label next to the switch. |
22
+ | `aria-label` | `string` | | Required when there is no `children`. |
23
+ | `disabled` | `boolean` | | |
24
+
25
+ Also `appearance`, `recipe`, `adaptation`, `className`, `style` and native `<input>` attributes except `type` and `role`. Native `onChange` receives an event, not a boolean: prefer `onCheckedChange`.
26
+
27
+ ## Slots
28
+
29
+ `root`, `input`, `track`, `thumb`, `label`.
30
+
31
+ ## Sizes by platform
32
+
33
+ | Platform | Size | Look |
34
+ | -------- | ----- | ------------------------ |
35
+ | Web | 44x26 | accent when on |
36
+ | Telegram | 51x31 | iOS switch, theme colour |
37
+ | Reddit | 48x32 | orange when on |
38
+
39
+ ## Recipes
40
+
41
+ `whatsappSwitch`: track 64x28, stretched thumb 38x24, green when on.
42
+
43
+ ## Correct
44
+
45
+ ```tsx
46
+ import { useState } from "react";
47
+
48
+ export function PublicProfileSetting() {
49
+ const [isPublic, setPublic] = useState(false);
50
+ return (
51
+ <Section footer="Friends can see your streaks and badges.">
52
+ <Cell
53
+ title="Public profile"
54
+ after={
55
+ <Switch aria-label="Public profile" checked={isPublic} onCheckedChange={setPublic} />
56
+ }
57
+ />
58
+ </Section>
59
+ );
60
+ }
61
+ ```
62
+
63
+ ## Wrong
64
+
65
+ ```tsx
66
+ // Raw checkbox styled as a toggle: no switch role, colours hard-coded.
67
+ <label className="toggle">
68
+ <input type="checkbox" checked={on} onChange={(e) => setOn(e.target.checked)} />
69
+ <span style={{ background: on ? "#34c759" : "#ccc" }} />
70
+ </label>
71
+
72
+ // onChange receives an event, not a boolean; and the switch has no name.
73
+ <Switch checked={on} onChange={(value) => setOn(value)} />
74
+ ```