@appss/ui 0.1.0 → 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 (41) hide show
  1. package/AGENTS.md +22 -340
  2. package/README.md +8 -1
  3. package/dist/index.d.ts +1 -0
  4. package/dist/index.d.ts.map +1 -1
  5. package/dist/index.js +1 -0
  6. package/dist/index.js.map +1 -1
  7. package/dist/styles.css +248 -180
  8. package/docs/components/Accordion.md +76 -0
  9. package/docs/components/Avatar.md +64 -0
  10. package/docs/components/Banner.md +70 -0
  11. package/docs/components/BottomNav.md +86 -0
  12. package/docs/components/Button.md +93 -0
  13. package/docs/components/Card.md +75 -0
  14. package/docs/components/Cell.md +89 -0
  15. package/docs/components/ChatListItem.md +102 -0
  16. package/docs/components/Dialog.md +93 -0
  17. package/docs/components/Divider.md +66 -0
  18. package/docs/components/IconButton.md +86 -0
  19. package/docs/components/Likes.md +74 -0
  20. package/docs/components/Link.md +79 -0
  21. package/docs/components/Menu.md +105 -0
  22. package/docs/components/MessageBubble.md +91 -0
  23. package/docs/components/MessageComposer.md +93 -0
  24. package/docs/components/MessageDivider.md +66 -0
  25. package/docs/components/NavBar.md +85 -0
  26. package/docs/components/NavList.md +85 -0
  27. package/docs/components/SearchField.md +81 -0
  28. package/docs/components/Section.md +81 -0
  29. package/docs/components/Stat.md +66 -0
  30. package/docs/components/Switch.md +74 -0
  31. package/docs/components/Tabs.md +85 -0
  32. package/docs/components/Tag.md +63 -0
  33. package/docs/components/Tooltip.md +62 -0
  34. package/docs/exports.json +90 -0
  35. package/docs/foundations.md +99 -0
  36. package/docs/gaps.json +12 -0
  37. package/docs/icons.md +20 -0
  38. package/docs/index.md +57 -0
  39. package/docs/recipes.md +43 -0
  40. package/docs/replaces.json +12 -0
  41. package/package.json +5 -2
@@ -0,0 +1,76 @@
1
+ # Accordion
2
+
3
+ Expandable blocks with a heading button each. `variant="list"` for rows such as FAQ or rules, `variant="section"` for collapsible sidebar groups with small uppercase headers.
4
+
5
+ Import `Accordion` from `@appss/ui`.
6
+
7
+ ## When to use
8
+
9
+ - FAQ, community rules (number in `leading`), details shown on demand.
10
+ - Collapsible groups of a site sidebar: `variant="section"` with a `NavList` as each `content`.
11
+ - Not for switching between views: use `Tabs`.
12
+ - Not for lists that should always be visible: use `Section`.
13
+
14
+ ## Props
15
+
16
+ | Prop | Type | Default | Notes |
17
+ | --------------- | ----------------------------------------------- | -------- | ------------------------------------ |
18
+ | `items` | `{ id, title, leading?, content, disabled? }[]` | required | `content` is required on every item. |
19
+ | `value` | `string[]` | | Controlled list of open ids. |
20
+ | `defaultValue` | `string[]` | `[]` | Uncontrolled initially open ids. |
21
+ | `onValueChange` | `(ids: string[]) => void` | | |
22
+ | `multiple` | `boolean` | `true` | `false` keeps only one item open. |
23
+ | `variant` | `"list" \| "section"` | `"list"` | |
24
+ | `headingLevel` | `2 \| 3 \| 4` | `3` | Heading level of each item. |
25
+
26
+ Also `appearance`, `recipe`, `adaptation`, `className`, `style` and native `<div>` attributes except `children`.
27
+
28
+ ## Slots
29
+
30
+ `root`, `item`, `header`, `trigger`, `leading`, `title`, `chevron`, `panel`.
31
+
32
+ ## Sizes by platform
33
+
34
+ | Platform | Row height |
35
+ | -------- | ----------------- |
36
+ | Web | 48 (`section` 40) |
37
+ | Telegram | 44 |
38
+ | Reddit | 40 |
39
+
40
+ ## Recipes
41
+
42
+ None.
43
+
44
+ ## Correct
45
+
46
+ ```tsx
47
+ const faq = [
48
+ {
49
+ id: "cancel",
50
+ title: "Can I cancel a booking?",
51
+ content: "Yes, free of charge up to 24 hours before the visit.",
52
+ },
53
+ {
54
+ id: "pay",
55
+ title: "When do I pay?",
56
+ content: "At the studio after the visit. Card and cash are accepted.",
57
+ },
58
+ ];
59
+
60
+ export function BookingFaq() {
61
+ return <Accordion items={faq} multiple={false} defaultValue={["cancel"]} headingLevel={2} />;
62
+ }
63
+ ```
64
+
65
+ ## Wrong
66
+
67
+ ```tsx
68
+ // Native details with hard-coded borders: no shared look, no platform styling.
69
+ <details style={{ borderBottom: "1px solid #eee" }}>
70
+ <summary>Can I cancel a booking?</summary>
71
+ Yes, up to 24 hours before.
72
+ </details>
73
+
74
+ // Invented props: items need id, title and content.
75
+ <Accordion title="FAQ" questions={faq} open />
76
+ ```
@@ -0,0 +1,64 @@
1
+ # Avatar
2
+
3
+ A photo or initials in a circle or rounded square. `name` is required: it is the accessible name and the source of the initials. Falls back to initials when the image fails.
4
+
5
+ Import `Avatar` from `@appss/ui`.
6
+
7
+ ## When to use
8
+
9
+ - People, shops, communities, bots and channels: in `Cell` `before`, `ChatListItem` `avatar`, `NavBar` `trailing`, a profile header (`size="2xl"`).
10
+ - An online dot: `status="online"`.
11
+ - A custom placeholder instead of initials: `fallback={<PersonIcon />}`.
12
+ - Not for product or cover photos: use an `<img>` inside a `Card`.
13
+ - Not for icons: use an icon from `@appss/ui/icons` directly.
14
+
15
+ ## Props
16
+
17
+ | Prop | Type | Default | Notes |
18
+ | ---------- | ----------------------------------------------- | ---------- | --------------------------------------------- |
19
+ | `name` | `string` | required | Alt text and initials. |
20
+ | `src` | `string` | | Image URL. |
21
+ | `fallback` | `ReactNode` | | Replaces the initials when there is no image. |
22
+ | `size` | `"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl"` | `"md"` | 20 / 24 / 32 / 40 / 64 / 112 px. |
23
+ | `shape` | `"circle" \| "rounded"` | `"circle"` | `rounded` for shops, groups and apps. |
24
+ | `status` | `"online" \| "offline"` | | Presence dot. |
25
+
26
+ Also `appearance`, `recipe`, `adaptation`, `className`, `style` and native `<span>` attributes except `children`.
27
+
28
+ ## Slots
29
+
30
+ `root`, `image`, `fallback`, `status`.
31
+
32
+ ## Sizes by platform
33
+
34
+ Same sizes everywhere: `xs` 20, `sm` 24, `md` 32, `lg` 40, `xl` 64, `2xl` 112. Placeholder colours follow the platform.
35
+
36
+ ## Recipes
37
+
38
+ `whatsappAvatar`: soft pastel placeholder; set its background through `style` if needed.
39
+
40
+ ## Correct
41
+
42
+ ```tsx
43
+ import { PersonIcon } from "@appss/ui/icons";
44
+
45
+ export function ProfileHeader() {
46
+ return (
47
+ <div style={{ display: "grid", justifyItems: "center", gap: 8, padding: "24px 16px" }}>
48
+ <Avatar name="Jordan K." size="2xl" fallback={<PersonIcon size={48} />} />
49
+ <strong style={{ fontSize: 22 }}>Jordan K.</strong>
50
+ <Avatar name="Coach" src="/images/coach.jpg" status="online" size="lg" />
51
+ </div>
52
+ );
53
+ }
54
+ ```
55
+
56
+ ## Wrong
57
+
58
+ ```tsx
59
+ // Raw image: no fallback when it fails, no initials, no accessible name.
60
+ <img src={user.photo} style={{ width: 40, height: 40, borderRadius: "50%" }} />
61
+
62
+ // Missing name (TypeScript error) and an invented size.
63
+ <Avatar src={user.photo} size={40} />
64
+ ```
@@ -0,0 +1,70 @@
1
+ # Banner
2
+
3
+ A highlighted link block with a coloured background: an announcement, a new feature, a call to action. Text is white, so the background must be dark enough.
4
+
5
+ Import `Banner` from `@appss/ui`.
6
+
7
+ ## When to use
8
+
9
+ - One call to action or announcement per screen: "Invite friends", "New: weekly challenges".
10
+ - Not for neutral content: use `Card`.
11
+ - Not for confirmations or blocking messages: use `Dialog`.
12
+
13
+ ## Props
14
+
15
+ | Prop | Type | Default | Notes |
16
+ | ---------- | ----------------- | --------------- | ---------------------------------------------------------------------------- |
17
+ | `href` | `string` | required | Banner is a link. |
18
+ | `title` | `ReactNode` | required | |
19
+ | `subtitle` | `ReactNode` | | |
20
+ | `caption` | `ReactNode` | | Small third line. |
21
+ | `icon` | `ReactNode` | | Icon or Avatar in the media slot. |
22
+ | `color` | `string` | platform colour | Background. Prefer a token such as `var(--app-accent)`; omit it in Telegram. |
23
+ | `onClick` | `(event) => void` | | Native; call `event.preventDefault()` for SPA routing. |
24
+
25
+ Also `appearance`, `recipe`, `adaptation`, `className`, `style` and native `<a>` attributes except `title`, `children` and `color`.
26
+
27
+ ## Slots
28
+
29
+ `root`, `media`, `content`, `title`, `subtitle`, `caption`.
30
+
31
+ ## Sizes by platform
32
+
33
+ | Platform | Look |
34
+ | -------- | ----------------------------------------------- |
35
+ | Web | padding 12x16, radius 16 |
36
+ | Telegram | radius 12, theme button colour by default |
37
+ | Reddit | radius 16, brand colour by default, 16 px title |
38
+
39
+ ## Recipes
40
+
41
+ None.
42
+
43
+ ## Correct
44
+
45
+ ```tsx
46
+ import { CommunitiesIcon } from "@appss/ui/icons";
47
+
48
+ export function InviteBanner() {
49
+ return (
50
+ <Banner
51
+ href="/invite"
52
+ icon={<CommunitiesIcon />}
53
+ title="Train with friends"
54
+ subtitle="Invite a friend and you both get a free week"
55
+ />
56
+ );
57
+ }
58
+ ```
59
+
60
+ ## Wrong
61
+
62
+ ```tsx
63
+ // Clickable div with a hard-coded gradient: not a link, not themed.
64
+ <div onClick={openInvite} style={{ background: "linear-gradient(90deg, #7f5af0, #2cb67d)" }}>
65
+ Train with friends
66
+ </div>
67
+
68
+ // A light background with white text is unreadable.
69
+ <Banner href="/invite" title="Train with friends" color="#fff8e1" />
70
+ ```
@@ -0,0 +1,86 @@
1
+ # BottomNav
2
+
3
+ Bottom tab bar of links for the app's main sections. Controlled: you own `activeId`.
4
+
5
+ Import `BottomNav` from `@appss/ui`.
6
+
7
+ ## When to use
8
+
9
+ - 3-5 top-level sections of a mobile app: Home, Search, Saved, Profile.
10
+ - Hide it while scrolling down: `modules={[hideOnScroll({ target })]}` from `@appss/ui/modules`.
11
+ - Not for views inside one screen: use `Tabs`.
12
+ - Not for a desktop sidebar or a site header: use `NavList`.
13
+
14
+ ## Props
15
+
16
+ | Prop | Type | Default | Notes |
17
+ | ------------ | ------------------------------------------------- | -------- | --------------------------------------------------------------------- |
18
+ | `items` | `{ id, label, href, icon?, badge?, disabled? }[]` | required | `href` is required on every item; `badge` is a number. |
19
+ | `activeId` | `string` | required | Id of the current section. |
20
+ | `onNavigate` | `(id, event) => void` | | Call `event.preventDefault()` for SPA routing, then set `activeId`. |
21
+ | `modules` | `BottomNavModule[]` | | E.g. `[hideOnScroll({ target })]`. |
22
+ | `aria-label` | `string` | | Pass an English name such as "Main"; the built-in default is Russian. |
23
+
24
+ Also `appearance`, `recipe`, `adaptation`, `className`, `style` and native `<nav>` attributes.
25
+
26
+ Placement is the app's job: wrap it in a fixed container at the bottom and leave bottom padding on the content. The component itself respects `safe-area-inset-bottom`.
27
+
28
+ ## Slots
29
+
30
+ `root`, `list`, `item`, `icon`, `label`, `badge`.
31
+
32
+ ## Sizes by platform
33
+
34
+ | Platform | Look |
35
+ | -------- | ---------------------------------------------------------------------------------------------------- |
36
+ | Web | white card, radius 18, min height 72 |
37
+ | Telegram | floating glass capsule sized to its content, centered, items 54, active item is a pill, red counters |
38
+ | Reddit | floating glass capsule, items 54, active item is a pill |
39
+
40
+ ## Recipes
41
+
42
+ `dockNav` (calm floating card), `lineNav` (strict full-width bar), `glassNav` (premium glass capsule), `whatsappTabBar` (friendly, green counters). See `docs/recipes.md`.
43
+
44
+ ## Correct
45
+
46
+ ```tsx
47
+ import { useState } from "react";
48
+ import { CheckIcon, PersonIcon, StatusIcon } from "@appss/ui/icons";
49
+ import { dockNav } from "@appss/ui/recipes";
50
+
51
+ const sections = [
52
+ { id: "today", label: "Today", href: "/", icon: <CheckIcon /> },
53
+ { id: "progress", label: "Progress", href: "/progress", icon: <StatusIcon /> },
54
+ { id: "profile", label: "Profile", href: "/profile", icon: <PersonIcon />, badge: 1 },
55
+ ];
56
+
57
+ export function AppTabs() {
58
+ const [active, setActive] = useState("today");
59
+ return (
60
+ <div style={{ position: "fixed", left: 12, right: 12, bottom: 12 }}>
61
+ <BottomNav
62
+ aria-label="Main"
63
+ recipe={dockNav}
64
+ items={sections}
65
+ activeId={active}
66
+ onNavigate={(id, event) => {
67
+ event.preventDefault();
68
+ setActive(id);
69
+ }}
70
+ />
71
+ </div>
72
+ );
73
+ }
74
+ ```
75
+
76
+ ## Wrong
77
+
78
+ ```tsx
79
+ // Hand-made tab bar: buttons instead of links, hard-coded active colour, no aria-current.
80
+ <div style={{ position: "fixed", bottom: 0, display: "flex", background: "#fff" }}>
81
+ <button style={{ color: active === "home" ? "#2481cc" : "#999" }}>Home</button>
82
+ </div>
83
+
84
+ // Invented props and missing href: items need href, the bar uses activeId and onNavigate.
85
+ <BottomNav items={[{ id: "home", label: "Home" }]} value="home" onChange={setTab} />
86
+ ```
@@ -0,0 +1,93 @@
1
+ # Button
2
+
3
+ Text button for any labelled action. One `variant="solid"` Button per screen marks the main action; everything else is `soft`, `outline` or `plain`.
4
+
5
+ Import `Button` from `@appss/ui`.
6
+
7
+ ## When to use
8
+
9
+ - Any action with a visible text label: save, book, add to cart, start.
10
+ - The screen's main action: `variant="solid"`, usually `size="lg"` and full width at the bottom.
11
+ - Secondary actions: `soft` (tinted), `outline` (bordered), `plain` (text only).
12
+ - Not for icon-only actions: use `IconButton`.
13
+ - Not for switching app sections: use `BottomNav`; not for a row that opens a screen: use `Cell`.
14
+
15
+ ## Props
16
+
17
+ | Prop | Type | Default | Notes |
18
+ | ---------- | --------------------------------------------------- | ---------- | ---------------------------------------------------------- |
19
+ | `children` | `ReactNode` | | The label text. |
20
+ | `variant` | `"solid" \| "soft" \| "outline" \| "plain"` | `"solid"` | Emphasis. |
21
+ | `tone` | `"accent" \| "neutral" \| "brand" \| "destructive"` | `"accent"` | `neutral` is dark or grey, `brand` the platform colour. |
22
+ | `size` | `"sm" \| "md" \| "lg"` | `"md"` | |
23
+ | `loading` | `boolean` | `false` | Shows a spinner, sets `aria-busy` and disables the button. |
24
+ | `leading` | `ReactNode` | | Icon before the label. |
25
+ | `trailing` | `ReactNode` | | Icon after the label. |
26
+ | `onClick` | `(event) => void` | | Native. |
27
+ | `disabled` | `boolean` | | Native. |
28
+ | `type` | `"button" \| "submit" \| "reset"` | `"button"` | Pass `"submit"` inside a form. |
29
+
30
+ Also `appearance`, `recipe`, `adaptation`, `className`, `style` and any native `<button>` attribute. There is no `fullWidth`, `icon` or `isLoading` prop, and `color` does nothing: use `style={{ width: "100%" }}`, `leading`, `loading` and `tone`.
31
+
32
+ ## Slots
33
+
34
+ `root`, `label`, `leading`, `trailing`, `spinner`. Tweak one instance with `appearance={{ classNames: { label: "my-class" } }}` or `appearance={{ styles: { root: { width: "100%" } } }}`.
35
+
36
+ ## Sizes by platform
37
+
38
+ | Platform | Heights sm / md / lg | Shape |
39
+ | -------- | -------------------- | ------------------------------------- |
40
+ | Web | 36 / 44 / 52 | radius 10 |
41
+ | Telegram | 36 / 42 / 50 | radius 20 for `sm`, 12 for the others |
42
+ | Reddit | 32 / 40 / 48 | pill |
43
+
44
+ ## Recipes
45
+
46
+ `essentialButton` (neutral, businesslike), `pillButton` (friendly, fully rounded), `softButton` (playful, raised with a bottom shadow). See `docs/recipes.md`.
47
+
48
+ ## Correct
49
+
50
+ ```tsx
51
+ import { useState } from "react";
52
+ import { PlusIcon } from "@appss/ui/icons";
53
+ import { pillButton } from "@appss/ui/recipes";
54
+
55
+ export function BookingActions() {
56
+ const [saving, setSaving] = useState(false);
57
+ return (
58
+ <div style={{ display: "grid", gap: 8 }}>
59
+ <Button
60
+ size="lg"
61
+ recipe={pillButton}
62
+ loading={saving}
63
+ style={{ width: "100%" }}
64
+ onClick={() => setSaving(true)}
65
+ >
66
+ Confirm booking
67
+ </Button>
68
+ <Button variant="soft" leading={<PlusIcon />}>
69
+ Add another service
70
+ </Button>
71
+ <Button variant="plain" tone="destructive">
72
+ Cancel booking
73
+ </Button>
74
+ </div>
75
+ );
76
+ }
77
+ ```
78
+
79
+ ## Wrong
80
+
81
+ ```tsx
82
+ // Raw element with a hard-coded colour: breaks Telegram themes and dark mode.
83
+ <button style={{ background: "#2481cc", color: "#fff", borderRadius: 8 }} onClick={save}>
84
+ Save
85
+ </button>
86
+
87
+ // Invented props: fullWidth and icon do not exist, and color is an inert HTML attribute.
88
+ <Button color="primary" fullWidth icon={<PlusIcon />}>Add</Button>
89
+
90
+ // Two solid buttons compete for attention.
91
+ <Button>Save</Button>
92
+ <Button>Share</Button>
93
+ ```
@@ -0,0 +1,75 @@
1
+ # Card
2
+
3
+ A surface for one block of content with an optional title and a header action. The default title style is a small uppercase caption; pass `titleStyle="heading"` for a regular heading.
4
+
5
+ Import `Card` from `@appss/ui`.
6
+
7
+ ## When to use
8
+
9
+ - Feed posts, dashboard widgets, product tiles, summaries.
10
+ - A block with a "See all" `Link` or a Join `Button` in `action`.
11
+ - Not for a list of rows: use `Section` with `Cell`.
12
+ - Not for a coloured promo: use `Banner`.
13
+
14
+ ## Props
15
+
16
+ | Prop | Type | Default | Notes |
17
+ | ------------ | -------------------------------------- | ----------- | ------------------------------------------------------- |
18
+ | `title` | `ReactNode` | | |
19
+ | `titleAs` | `"h2" \| "h3" \| "div"` | `"h2"` | Heading level. |
20
+ | `titleStyle` | `"caption" \| "heading"` | `"caption"` | `caption` = small uppercase; `heading` = regular title. |
21
+ | `action` | `ReactNode` | | Header action: a Link, Button or IconButton. |
22
+ | `variant` | `"filled" \| "outlined" \| "elevated"` | `"filled"` | |
23
+ | `children` | `ReactNode` | | Body. |
24
+
25
+ Also `appearance`, `recipe`, `adaptation`, `className`, `style` and native `<section>` attributes except `title`. There is no `image`, `footer` or `onClick` card API: put an `<img>` and your own footer row in `children`, and a Button or Link for the action.
26
+
27
+ ## Slots
28
+
29
+ `root`, `header`, `title`, `action`, `body`.
30
+
31
+ ## Sizes by platform
32
+
33
+ | Platform | Padding | Radius |
34
+ | -------- | ------- | ------ |
35
+ | Web | 16 | 16 |
36
+ | Telegram | 16 | 12 |
37
+ | Reddit | 16 | 16 |
38
+
39
+ ## Recipes
40
+
41
+ None.
42
+
43
+ ## Correct
44
+
45
+ ```tsx
46
+ export function ProductTile() {
47
+ return (
48
+ <Card variant="outlined" title="Linen throw" titleAs="h3" titleStyle="heading">
49
+ <img
50
+ src="/images/throw.jpg"
51
+ alt="Linen throw in sand colour"
52
+ style={{ width: "100%", aspectRatio: "4 / 3", objectFit: "cover", borderRadius: 8 }}
53
+ />
54
+ <div style={{ display: "flex", alignItems: "center", justifyContent: "space-between" }}>
55
+ <strong>$64</strong>
56
+ <Button size="sm" variant="soft">
57
+ Add to cart
58
+ </Button>
59
+ </div>
60
+ </Card>
61
+ );
62
+ }
63
+ ```
64
+
65
+ ## Wrong
66
+
67
+ ```tsx
68
+ // Hand-made card with a hard-coded background and shadow.
69
+ <div style={{ background: "#fff", borderRadius: 16, boxShadow: "0 2px 8px rgba(0,0,0,.1)" }}>
70
+ <h3>Linen throw</h3>
71
+ </div>
72
+
73
+ // Invented props.
74
+ <Card image="/throw.jpg" footer={<Button>Add</Button>} onClick={open} />
75
+ ```
@@ -0,0 +1,89 @@
1
+ # Cell
2
+
3
+ One row of a `Section`: a leading icon or avatar, a title and subtitle, and a trailing value, chevron or control. With `href` it is a link, with `onClick` a button, otherwise a static row.
4
+
5
+ Import `Cell` from `@appss/ui`. It lives next to `Section` and is always used inside one.
6
+
7
+ ## When to use
8
+
9
+ - Rows inside a `Section`: settings, menu entries, order lines, time slots.
10
+ - A row that opens a screen (`href`) or runs an action (`onClick`).
11
+ - A setting with a `Switch` in `after` (keep that Cell static: no `href` or `onClick`).
12
+ - A value on the right: a price, a time, a count, as `after`.
13
+ - Not for conversations: use `ChatListItem`.
14
+ - Not for a standalone action outside a list: use `Button`.
15
+
16
+ ## Props
17
+
18
+ | Prop | Type | Default | Notes |
19
+ | ---------- | ----------------- | -------- | ------------------------------------------------------ |
20
+ | `title` | `ReactNode` | required | |
21
+ | `subtitle` | `ReactNode` | | Second line in a softer colour. |
22
+ | `before` | `ReactNode` | | Leading icon or `Avatar`. |
23
+ | `after` | `ReactNode` | | Trailing value, `ChevronRightIcon`, `Tag` or `Switch`. |
24
+ | `href` | `string` | | Renders a link. |
25
+ | `onClick` | `(event) => void` | | Without `href`, renders a button. |
26
+ | `disabled` | `boolean` | | |
27
+
28
+ Also `appearance`, `recipe`, `adaptation`, `className`, `style` and native attributes except `title`. There is no `icon`, `value`, `label`, `description` or `onPress` prop: use `before`, `after`, `title`, `subtitle` and `onClick`.
29
+
30
+ ## Slots
31
+
32
+ `root`, `before`, `content`, `title`, `subtitle`, `after`. (Not `leading` / `trailing`: those are Button and Link slots.)
33
+
34
+ ## Sizes by platform
35
+
36
+ | Platform | Row height | Look |
37
+ | -------- | ---------- | --------------------------------------- |
38
+ | Web | 52 | separators between rows |
39
+ | Telegram | 44 | 17 px text, separator inset to the text |
40
+ | Reddit | 48 | dense |
41
+
42
+ ## Recipes
43
+
44
+ `whatsappCell`: row 52, 17 px text, 24 px icon on the left, separator starting at the text. Use with `whatsappSection`.
45
+
46
+ ## Correct
47
+
48
+ ```tsx
49
+ import { ChevronRightIcon } from "@appss/ui/icons";
50
+
51
+ const slots = [
52
+ { id: "s1", time: "10:00", master: "Anna, senior stylist", free: true },
53
+ { id: "s2", time: "11:30", master: "Mark, stylist", free: false },
54
+ ];
55
+
56
+ export function SlotList({ onPick }: { onPick: (id: string) => void }) {
57
+ return (
58
+ <Section header="Tuesday, 14 May">
59
+ {slots.map((slot) => (
60
+ <Cell
61
+ key={slot.id}
62
+ title={slot.time}
63
+ subtitle={slot.master}
64
+ before={<Avatar name={slot.master} size="lg" />}
65
+ after={slot.free ? <ChevronRightIcon /> : <Tag tone="neutral">Booked</Tag>}
66
+ disabled={!slot.free}
67
+ onClick={() => onPick(slot.id)}
68
+ />
69
+ ))}
70
+ </Section>
71
+ );
72
+ }
73
+ ```
74
+
75
+ ## Wrong
76
+
77
+ ```tsx
78
+ // Raw clickable div: not focusable, no keyboard support, hard-coded divider colour.
79
+ <div onClick={open} style={{ display: "flex", padding: 12, borderBottom: "1px solid #e5e5e5" }}>
80
+ <span>Privacy</span>
81
+ <span>›</span>
82
+ </div>
83
+
84
+ // Invented props.
85
+ <Cell icon={<LockIcon />} label="Privacy" value="On" onPress={open} />
86
+
87
+ // A Switch inside an interactive Cell nests a control inside a button.
88
+ <Cell title="Reminders" onClick={toggle} after={<Switch aria-label="Reminders" />} />
89
+ ```
@@ -0,0 +1,102 @@
1
+ # ChatListItem
2
+
3
+ A conversation row: avatar, name, time, last message preview, delivery status, unread counter, muted and pinned marks, folder tags.
4
+
5
+ Import `ChatListItem` from `@appss/ui`.
6
+
7
+ ## When to use
8
+
9
+ - Chat, inbox, support ticket and conversation lists.
10
+ - Any row with a last message and an unread counter.
11
+ - Group chats: `sender` shows who wrote the last message.
12
+ - Not for settings or data rows: use `Cell` in a `Section`.
13
+ - Not for feed posts: use `Card`.
14
+
15
+ ## Props
16
+
17
+ | Prop | Type | Default | Notes |
18
+ | -------------- | ---------------------------------------------- | -------- | --------------------------------------------------------- |
19
+ | `name` | `ReactNode` | required | |
20
+ | `avatar` | `ReactNode` | | Usually an `Avatar` (`size="xl"` in Telegram-like lists). |
21
+ | `preview` | `ReactNode` | | Last message text. |
22
+ | `sender` | `ReactNode` | | Author of the last message in a group. |
23
+ | `time` | `string` | | Already formatted: "09:41", "Tue", "12/05". |
24
+ | `unreadCount` | `number` | | Counter; shows 999+ above 999. |
25
+ | `status` | `"sending" \| "sent" \| "delivered" \| "read"` | | Delivery of the user's own last message. |
26
+ | `muted` | `boolean` | `false` | Muted icon and a neutral counter. |
27
+ | `pinned` | `boolean` | `false` | Pin icon when there is no counter. |
28
+ | `tags` | `ReactNode` | | Folder labels, e.g. `Tag`s. |
29
+ | `previewLines` | `1 \| 2` | `2` | |
30
+ | `href` | `string` | | Renders a link; with `onClick` and no `href`, a button. |
31
+ | `onClick` | `(event) => void` | | |
32
+
33
+ Also `appearance`, `recipe`, `adaptation`, `className`, `style` and native attributes except `title`.
34
+
35
+ ## Slots
36
+
37
+ `root`, `avatar`, `content`, `header`, `name`, `muted`, `timeStatus`, `time`, `body`, `status`, `sender`, `preview`, `badge`, `pin`, `tags`.
38
+
39
+ ## Sizes by platform
40
+
41
+ | Platform | Look |
42
+ | -------- | ------------------------------------------------------------------------------------ |
43
+ | Web | padding 8x16, name 16, preview 14 on two lines |
44
+ | Telegram | avatar 54, name 17, check mark by the time, grey counter for muted chats, inset line |
45
+ | Reddit | compact, 14 px |
46
+
47
+ ## Recipes
48
+
49
+ `whatsappChatListItem`: avatar 52, name 17/600, grey 15 px preview, green time and counter when unread, blue read ticks.
50
+
51
+ ## Correct
52
+
53
+ ```tsx
54
+ export function Inbox() {
55
+ return (
56
+ <div>
57
+ <ChatListItem
58
+ href="/chats/design"
59
+ avatar={<Avatar name="Design team" size="xl" />}
60
+ name="Design team"
61
+ sender="Lena"
62
+ preview="Moved the review to 3 pm, the room is booked"
63
+ time="09:41"
64
+ unreadCount={4}
65
+ tags={<Tag tone="accent">Work</Tag>}
66
+ />
67
+ <ChatListItem
68
+ href="/chats/support"
69
+ avatar={<Avatar name="Support" size="xl" shape="rounded" />}
70
+ name="Support"
71
+ preview="Your refund has been processed"
72
+ time="Tue"
73
+ status="read"
74
+ pinned
75
+ />
76
+ <ChatListItem
77
+ href="/chats/building"
78
+ avatar={<Avatar name="Building chat" size="xl" />}
79
+ name="Building chat"
80
+ preview="Water will be off on Friday from 10 to 14"
81
+ time="Mon"
82
+ unreadCount={12}
83
+ muted
84
+ />
85
+ </div>
86
+ );
87
+ }
88
+ ```
89
+
90
+ ## Wrong
91
+
92
+ ```tsx
93
+ // Hand-made row with hard-coded unread colour and truncation logic.
94
+ <div className="chat-row" onClick={open}>
95
+ <img src={chat.photo} className="round" />
96
+ <b>{chat.name}</b>
97
+ <span style={{ background: "#2481cc", color: "#fff", borderRadius: 10 }}>{chat.unread}</span>
98
+ </div>
99
+
100
+ // Invented props.
101
+ <ChatListItem title={chat.name} message={chat.last} unread={chat.unread} onPress={open} />
102
+ ```