@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.
- package/AGENTS.md +22 -340
- package/README.md +8 -1
- package/dist/index.d.ts +1 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -0
- package/dist/index.js.map +1 -1
- package/dist/styles.css +248 -180
- package/docs/components/Accordion.md +76 -0
- package/docs/components/Avatar.md +64 -0
- package/docs/components/Banner.md +70 -0
- package/docs/components/BottomNav.md +86 -0
- package/docs/components/Button.md +93 -0
- package/docs/components/Card.md +75 -0
- package/docs/components/Cell.md +89 -0
- package/docs/components/ChatListItem.md +102 -0
- package/docs/components/Dialog.md +93 -0
- package/docs/components/Divider.md +66 -0
- package/docs/components/IconButton.md +86 -0
- package/docs/components/Likes.md +74 -0
- package/docs/components/Link.md +79 -0
- package/docs/components/Menu.md +105 -0
- package/docs/components/MessageBubble.md +91 -0
- package/docs/components/MessageComposer.md +93 -0
- package/docs/components/MessageDivider.md +66 -0
- package/docs/components/NavBar.md +85 -0
- package/docs/components/NavList.md +85 -0
- package/docs/components/SearchField.md +81 -0
- package/docs/components/Section.md +81 -0
- package/docs/components/Stat.md +66 -0
- package/docs/components/Switch.md +74 -0
- package/docs/components/Tabs.md +85 -0
- package/docs/components/Tag.md +63 -0
- package/docs/components/Tooltip.md +62 -0
- package/docs/exports.json +90 -0
- package/docs/foundations.md +99 -0
- package/docs/gaps.json +12 -0
- package/docs/icons.md +20 -0
- package/docs/index.md +57 -0
- package/docs/recipes.md +43 -0
- package/docs/replaces.json +12 -0
- package/package.json +5 -2
|
@@ -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
|
+
```
|