experiments in a post-browser web
10
fork

Configure Feed

Select the types of activity you want to include in your feed.

docs(components): add Phase 4.1 component documentation to README

+361
+361
app/components/README.md
··· 1008 1008 1009 1009 --- 1010 1010 1011 + ## Phase 4 Components 1012 + 1013 + ### `<peek-select>` 1014 + 1015 + Select/combobox with native and custom modes. 1016 + 1017 + #### Properties 1018 + 1019 + | Property | Type | Default | Description | 1020 + |----------|------|---------|-------------| 1021 + | `value` | `string` | `''` | Selected value | 1022 + | `placeholder` | `string` | `'Select...'` | Placeholder text | 1023 + | `disabled` | `boolean` | `false` | Disable the select | 1024 + | `required` | `boolean` | `false` | Mark as required | 1025 + | `multiple` | `boolean` | `false` | Allow multiple (native mode only) | 1026 + | `mode` | `'native' \| 'custom'` | `'native'` | Native `<select>` or custom Popover | 1027 + | `options` | `Array` | `[]` | Options: strings or `{ value, label, disabled }` | 1028 + | `name` | `string` | `''` | Form field name | 1029 + 1030 + #### Events 1031 + 1032 + | Event | Detail | Description | 1033 + |-------|--------|-------------| 1034 + | `change` | `{ value, option }` | When selection changes | 1035 + 1036 + #### Example 1037 + 1038 + ```html 1039 + <!-- Native select --> 1040 + <peek-select 1041 + placeholder="Choose a color" 1042 + .options=${['Red', 'Green', 'Blue']} 1043 + @change=${(e) => console.log(e.detail.value)} 1044 + ></peek-select> 1045 + 1046 + <!-- Custom styled select --> 1047 + <peek-select 1048 + mode="custom" 1049 + .options=${[ 1050 + { value: 'sm', label: 'Small' }, 1051 + { value: 'md', label: 'Medium' }, 1052 + { value: 'lg', label: 'Large', disabled: true } 1053 + ]} 1054 + ></peek-select> 1055 + ``` 1056 + 1057 + --- 1058 + 1059 + ### `<peek-dropdown>`, `<peek-dropdown-item>`, `<peek-dropdown-divider>` 1060 + 1061 + Action menu / context menu using Popover API. 1062 + 1063 + #### `<peek-dropdown>` Properties 1064 + 1065 + | Property | Type | Default | Description | 1066 + |----------|------|---------|-------------| 1067 + | `open` | `boolean` | `false` | Whether dropdown is open | 1068 + | `position` | `'bottom-start' \| 'bottom-end' \| 'top-start' \| 'top-end'` | `'bottom-start'` | Position relative to trigger | 1069 + | `disabled` | `boolean` | `false` | Disable the trigger | 1070 + 1071 + #### `<peek-dropdown-item>` Properties 1072 + 1073 + | Property | Type | Default | Description | 1074 + |----------|------|---------|-------------| 1075 + | `value` | `string` | `''` | Item value | 1076 + | `disabled` | `boolean` | `false` | Disable this item | 1077 + | `danger` | `boolean` | `false` | Style as destructive action | 1078 + 1079 + #### Slots 1080 + 1081 + **`<peek-dropdown>`:** 1082 + | Slot | Description | 1083 + |------|-------------| 1084 + | `trigger` | Element that triggers the dropdown | 1085 + | (default) | Menu content | 1086 + 1087 + **`<peek-dropdown-item>`:** 1088 + | Slot | Description | 1089 + |------|-------------| 1090 + | `prefix` | Icon before label | 1091 + | (default) | Item label | 1092 + | `suffix` | Shortcut text after label | 1093 + 1094 + #### Events 1095 + 1096 + | Event | Detail | Description | 1097 + |-------|--------|-------------| 1098 + | `open` | — | When dropdown opens | 1099 + | `close` | — | When dropdown closes | 1100 + | `select` | `{ value, item }` | When item is selected | 1101 + 1102 + #### Example 1103 + 1104 + ```html 1105 + <peek-dropdown @select=${(e) => handleAction(e.detail.value)}> 1106 + <peek-button slot="trigger">Actions</peek-button> 1107 + 1108 + <peek-dropdown-item value="edit"> 1109 + <svg slot="prefix">...</svg> 1110 + Edit 1111 + <span slot="suffix">⌘E</span> 1112 + </peek-dropdown-item> 1113 + <peek-dropdown-item value="duplicate">Duplicate</peek-dropdown-item> 1114 + <peek-dropdown-divider></peek-dropdown-divider> 1115 + <peek-dropdown-item value="delete" danger>Delete</peek-dropdown-item> 1116 + </peek-dropdown> 1117 + ``` 1118 + 1119 + --- 1120 + 1121 + ### `<peek-switch>` 1122 + 1123 + Toggle switch built on native checkbox. 1124 + 1125 + #### Properties 1126 + 1127 + | Property | Type | Default | Description | 1128 + |----------|------|---------|-------------| 1129 + | `checked` | `boolean` | `false` | Whether switch is on | 1130 + | `disabled` | `boolean` | `false` | Disable the switch | 1131 + | `name` | `string` | `''` | Form field name | 1132 + | `value` | `string` | `'on'` | Form value when checked | 1133 + | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Switch size | 1134 + 1135 + #### Slots 1136 + 1137 + | Slot | Description | 1138 + |------|-------------| 1139 + | (default) | Label text | 1140 + | `on` | Content shown when on (inside track) | 1141 + | `off` | Content shown when off (inside track) | 1142 + 1143 + #### Events 1144 + 1145 + | Event | Detail | Description | 1146 + |-------|--------|-------------| 1147 + | `change` | `{ checked }` | When checked state changes | 1148 + 1149 + #### Methods 1150 + 1151 + | Method | Description | 1152 + |--------|-------------| 1153 + | `toggle()` | Toggle checked state | 1154 + 1155 + #### Example 1156 + 1157 + ```html 1158 + <!-- Basic switch --> 1159 + <peek-switch @change=${(e) => setDarkMode(e.detail.checked)}> 1160 + Dark mode 1161 + </peek-switch> 1162 + 1163 + <!-- With on/off labels --> 1164 + <peek-switch checked> 1165 + <span slot="on">ON</span> 1166 + <span slot="off">OFF</span> 1167 + Notifications 1168 + </peek-switch> 1169 + 1170 + <!-- Sizes --> 1171 + <peek-switch size="sm">Small</peek-switch> 1172 + <peek-switch size="lg">Large</peek-switch> 1173 + ``` 1174 + 1175 + --- 1176 + 1177 + ### `<peek-drawer>` 1178 + 1179 + Slide-out panel using native `<dialog>`. 1180 + 1181 + #### Properties 1182 + 1183 + | Property | Type | Default | Description | 1184 + |----------|------|---------|-------------| 1185 + | `open` | `boolean` | `false` | Whether drawer is open | 1186 + | `position` | `'left' \| 'right' \| 'top' \| 'bottom'` | `'left'` | Slide direction | 1187 + | `size` | `'sm' \| 'md' \| 'lg' \| 'full'` or CSS value | `'md'` | Drawer size | 1188 + | `modal` | `boolean` | `true` | Show with backdrop | 1189 + | `close-on-backdrop` | `boolean` | `true` | Close on backdrop click | 1190 + | `close-on-escape` | `boolean` | `true` | Close on Escape key | 1191 + | `contained` | `boolean` | `false` | Constrain to parent instead of viewport | 1192 + 1193 + #### Slots 1194 + 1195 + | Slot | Description | 1196 + |------|-------------| 1197 + | `header` | Drawer header/title | 1198 + | (default) | Drawer content | 1199 + | `footer` | Footer with actions | 1200 + 1201 + #### CSS Parts 1202 + 1203 + | Part | Description | 1204 + |------|-------------| 1205 + | `drawer` | The dialog element | 1206 + | `header` | Header section | 1207 + | `body` | Body section | 1208 + | `footer` | Footer section | 1209 + 1210 + #### Events 1211 + 1212 + | Event | Detail | Description | 1213 + |-------|--------|-------------| 1214 + | `open` | — | When drawer opens | 1215 + | `close` | `{ reason }` | When drawer closes (`'escape' \| 'backdrop' \| 'close' \| 'api'`) | 1216 + 1217 + #### Methods 1218 + 1219 + | Method | Description | 1220 + |--------|-------------| 1221 + | `show()` | Open the drawer | 1222 + | `showModal()` | Open as modal | 1223 + | `close()` | Close the drawer | 1224 + 1225 + #### Example 1226 + 1227 + ```html 1228 + <peek-drawer id="settingsDrawer" position="right" size="400px"> 1229 + <span slot="header">Settings</span> 1230 + 1231 + <peek-list> 1232 + <peek-list-item>Profile</peek-list-item> 1233 + <peek-list-item>Preferences</peek-list-item> 1234 + <peek-list-item>Security</peek-list-item> 1235 + </peek-list> 1236 + 1237 + <div slot="footer"> 1238 + <peek-button @click=${() => settingsDrawer.close()}>Close</peek-button> 1239 + </div> 1240 + </peek-drawer> 1241 + 1242 + <peek-button @click=${() => settingsDrawer.show()}>Open Settings</peek-button> 1243 + ``` 1244 + 1245 + --- 1246 + 1247 + ### `<peek-tooltip>` 1248 + 1249 + Hover-triggered tooltip using Popover API. 1250 + 1251 + #### Properties 1252 + 1253 + | Property | Type | Default | Description | 1254 + |----------|------|---------|-------------| 1255 + | `content` | `string` | `''` | Tooltip text | 1256 + | `position` | `'top' \| 'bottom' \| 'left' \| 'right'` | `'top'` | Position relative to target | 1257 + | `delay` | `number` | `200` | Delay before showing (ms) | 1258 + | `disabled` | `boolean` | `false` | Disable the tooltip | 1259 + 1260 + #### Slots 1261 + 1262 + | Slot | Description | 1263 + |------|-------------| 1264 + | (default) | Target element | 1265 + 1266 + #### Methods 1267 + 1268 + | Method | Description | 1269 + |--------|-------------| 1270 + | `show()` | Show tooltip immediately | 1271 + | `hide()` | Hide tooltip | 1272 + 1273 + #### Example 1274 + 1275 + ```html 1276 + <!-- Basic tooltip --> 1277 + <peek-tooltip content="Save your changes"> 1278 + <peek-button>Save</peek-button> 1279 + </peek-tooltip> 1280 + 1281 + <!-- Different positions --> 1282 + <peek-tooltip content="Top" position="top"> 1283 + <span>Hover me</span> 1284 + </peek-tooltip> 1285 + 1286 + <peek-tooltip content="Right side" position="right" delay="0"> 1287 + <span>Instant tooltip</span> 1288 + </peek-tooltip> 1289 + ``` 1290 + 1291 + --- 1292 + 1293 + ### `<peek-button-group>`, `<peek-button-group-item>` 1294 + 1295 + Segmented controls and tag sets with selection. 1296 + 1297 + #### `<peek-button-group>` Properties 1298 + 1299 + | Property | Type | Default | Description | 1300 + |----------|------|---------|-------------| 1301 + | `value` | `string` | `''` | Selected value (single selection) | 1302 + | `values` | `Array` | `[]` | Selected values (multiple selection) | 1303 + | `selection` | `'none' \| 'single' \| 'multiple'` | `'single'` | Selection mode | 1304 + | `variant` | `'outline' \| 'ghost'` | `'outline'` | Visual style | 1305 + | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Button size | 1306 + | `disabled` | `boolean` | `false` | Disable all buttons | 1307 + 1308 + #### `<peek-button-group-item>` Properties 1309 + 1310 + | Property | Type | Default | Description | 1311 + |----------|------|---------|-------------| 1312 + | `value` | `string` | `''` | Item value | 1313 + | `disabled` | `boolean` | `false` | Disable this item | 1314 + 1315 + #### Slots 1316 + 1317 + **`<peek-button-group-item>`:** 1318 + | Slot | Description | 1319 + |------|-------------| 1320 + | `prefix` | Icon before label | 1321 + | (default) | Button label | 1322 + | `suffix` | Icon after label | 1323 + 1324 + #### Events 1325 + 1326 + | Event | Detail | Description | 1327 + |-------|--------|-------------| 1328 + | `change` | `{ value, values }` | When selection changes | 1329 + 1330 + #### Methods 1331 + 1332 + | Method | Description | 1333 + |--------|-------------| 1334 + | `select(value)` | Select an item | 1335 + | `deselect(value)` | Deselect an item | 1336 + | `clear()` | Clear all selections | 1337 + 1338 + #### Example 1339 + 1340 + ```html 1341 + <!-- Segmented control (single selection) --> 1342 + <peek-button-group value="day" @change=${(e) => setView(e.detail.value)}> 1343 + <peek-button-group-item value="day">Day</peek-button-group-item> 1344 + <peek-button-group-item value="week">Week</peek-button-group-item> 1345 + <peek-button-group-item value="month">Month</peek-button-group-item> 1346 + </peek-button-group> 1347 + 1348 + <!-- Tag set (multiple selection) --> 1349 + <peek-button-group 1350 + selection="multiple" 1351 + variant="ghost" 1352 + .values=${['urgent', 'work']} 1353 + > 1354 + <peek-button-group-item value="urgent">Urgent</peek-button-group-item> 1355 + <peek-button-group-item value="work">Work</peek-button-group-item> 1356 + <peek-button-group-item value="personal">Personal</peek-button-group-item> 1357 + </peek-button-group> 1358 + 1359 + <!-- With icons --> 1360 + <peek-button-group selection="single" size="sm"> 1361 + <peek-button-group-item value="list"> 1362 + <svg slot="prefix">...</svg> 1363 + </peek-button-group-item> 1364 + <peek-button-group-item value="grid"> 1365 + <svg slot="prefix">...</svg> 1366 + </peek-button-group-item> 1367 + </peek-button-group> 1368 + ``` 1369 + 1370 + --- 1371 + 1011 1372 ## Browser Support 1012 1373 1013 1374 Components use modern CSS and HTML features: