@xerios/design-system 0.0.0-stage → 0.1.1
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/LICENSE +21 -0
- package/README.md +403 -2
- package/dist/components/AnchorHeading.svelte +79 -0
- package/dist/components/AnchorHeading.svelte.d.ts +28 -0
- package/dist/components/Breadcrumbs.svelte +216 -0
- package/dist/components/Breadcrumbs.svelte.d.ts +37 -0
- package/dist/components/Button.svelte +185 -0
- package/dist/components/Button.svelte.d.ts +70 -0
- package/dist/components/Canvas.svelte +248 -0
- package/dist/components/Canvas.svelte.d.ts +91 -0
- package/dist/components/Collapsible.svelte +139 -0
- package/dist/components/Collapsible.svelte.d.ts +52 -0
- package/dist/components/CollapsibleAdvanced.svelte +174 -0
- package/dist/components/CollapsibleAdvanced.svelte.d.ts +43 -0
- package/dist/components/DashOutline.svelte +47 -0
- package/dist/components/DashOutline.svelte.d.ts +6 -0
- package/dist/components/Dialogs.svelte +123 -0
- package/dist/components/Dialogs.svelte.d.ts +6 -0
- package/dist/components/Drawer.svelte +231 -0
- package/dist/components/Drawer.svelte.d.ts +62 -0
- package/dist/components/ErrorMessage.svelte +140 -0
- package/dist/components/ErrorMessage.svelte.d.ts +41 -0
- package/dist/components/Icon.svelte +94 -0
- package/dist/components/Icon.svelte.d.ts +33 -0
- package/dist/components/InfoTip.svelte +183 -0
- package/dist/components/InfoTip.svelte.d.ts +28 -0
- package/dist/components/Md.svelte +28 -0
- package/dist/components/Md.svelte.d.ts +11 -0
- package/dist/components/Modal.svelte +91 -0
- package/dist/components/Modal.svelte.d.ts +41 -0
- package/dist/components/Notice.svelte +50 -0
- package/dist/components/Notice.svelte.d.ts +30 -0
- package/dist/components/Popover.svelte +212 -0
- package/dist/components/Popover.svelte.d.ts +70 -0
- package/dist/components/Shimmer.svelte +27 -0
- package/dist/components/Shimmer.svelte.d.ts +22 -0
- package/dist/components/Splitter.svelte +152 -0
- package/dist/components/Splitter.svelte.d.ts +41 -0
- package/dist/components/Table.svelte +448 -0
- package/dist/components/Table.svelte.d.ts +268 -0
- package/dist/components/Toast.svelte +273 -0
- package/dist/components/Toast.svelte.d.ts +31 -0
- package/dist/components/Tooltip.svelte +97 -0
- package/dist/components/Tooltip.svelte.d.ts +19 -0
- package/dist/components/WorkingBorder.svelte +105 -0
- package/dist/components/WorkingBorder.svelte.d.ts +26 -0
- package/dist/components/empty/Empty.svelte +55 -0
- package/dist/components/empty/Empty.svelte.d.ts +39 -0
- package/dist/components/empty/EmptyError.svelte +47 -0
- package/dist/components/empty/EmptyError.svelte.d.ts +28 -0
- package/dist/components/empty/index.d.ts +18 -0
- package/dist/components/empty/index.js +10 -0
- package/dist/components/filters/DateFilter.svelte +59 -0
- package/dist/components/filters/DateFilter.svelte.d.ts +23 -0
- package/dist/components/filters/FilterBar.svelte +401 -0
- package/dist/components/filters/FilterBar.svelte.d.ts +283 -0
- package/dist/components/filters/FilterChip.svelte +235 -0
- package/dist/components/filters/FilterChip.svelte.d.ts +68 -0
- package/dist/components/filters/OptionList.svelte +352 -0
- package/dist/components/filters/OptionList.svelte.d.ts +91 -0
- package/dist/components/filters/Panel.svelte +123 -0
- package/dist/components/filters/Panel.svelte.d.ts +25 -0
- package/dist/components/filters/index.d.ts +288 -0
- package/dist/components/filters/index.js +12 -0
- package/dist/components/icons.d.ts +54 -0
- package/dist/components/icons.js +58 -0
- package/dist/components/inputs/ButtonGroup.svelte +110 -0
- package/dist/components/inputs/ButtonGroup.svelte.d.ts +40 -0
- package/dist/components/inputs/Calendar.svelte +535 -0
- package/dist/components/inputs/Calendar.svelte.d.ts +45 -0
- package/dist/components/inputs/DateField.svelte +247 -0
- package/dist/components/inputs/DateField.svelte.d.ts +74 -0
- package/dist/components/inputs/DateInput.svelte +118 -0
- package/dist/components/inputs/DateInput.svelte.d.ts +43 -0
- package/dist/components/inputs/DatePicker.svelte +102 -0
- package/dist/components/inputs/DatePicker.svelte.d.ts +67 -0
- package/dist/components/inputs/DateRangePicker.svelte +208 -0
- package/dist/components/inputs/DateRangePicker.svelte.d.ts +76 -0
- package/dist/components/inputs/DateRangeSelect.svelte +548 -0
- package/dist/components/inputs/DateRangeSelect.svelte.d.ts +70 -0
- package/dist/components/inputs/FieldLabel.svelte +43 -0
- package/dist/components/inputs/FieldLabel.svelte.d.ts +28 -0
- package/dist/components/inputs/ListSearch.svelte +142 -0
- package/dist/components/inputs/ListSearch.svelte.d.ts +35 -0
- package/dist/components/inputs/RadioGroup.svelte +151 -0
- package/dist/components/inputs/RadioGroup.svelte.d.ts +49 -0
- package/dist/components/inputs/RangeShortcuts.svelte +90 -0
- package/dist/components/inputs/RangeShortcuts.svelte.d.ts +31 -0
- package/dist/components/inputs/RangeSlider.svelte +225 -0
- package/dist/components/inputs/RangeSlider.svelte.d.ts +37 -0
- package/dist/components/inputs/SearchField.svelte +24 -0
- package/dist/components/inputs/SearchField.svelte.d.ts +41 -0
- package/dist/components/inputs/Segmented.svelte +79 -0
- package/dist/components/inputs/Segmented.svelte.d.ts +43 -0
- package/dist/components/inputs/Select.svelte +552 -0
- package/dist/components/inputs/Select.svelte.d.ts +100 -0
- package/dist/components/inputs/Slider.svelte +177 -0
- package/dist/components/inputs/Slider.svelte.d.ts +33 -0
- package/dist/components/inputs/SliderTicks.svelte +62 -0
- package/dist/components/inputs/SliderTicks.svelte.d.ts +23 -0
- package/dist/components/inputs/Switch.svelte +120 -0
- package/dist/components/inputs/Switch.svelte.d.ts +31 -0
- package/dist/components/inputs/TagInput.svelte +296 -0
- package/dist/components/inputs/TagInput.svelte.d.ts +61 -0
- package/dist/components/inputs/TextArea.svelte +86 -0
- package/dist/components/inputs/TextArea.svelte.d.ts +56 -0
- package/dist/components/inputs/TextField.svelte +170 -0
- package/dist/components/inputs/TextField.svelte.d.ts +80 -0
- package/dist/components/menu/ContextMenu.svelte +25 -0
- package/dist/components/menu/ContextMenu.svelte.d.ts +26 -0
- package/dist/components/menu/MenuButton.svelte +46 -0
- package/dist/components/menu/MenuButton.svelte.d.ts +16 -0
- package/dist/components/menu/MenuList.svelte +319 -0
- package/dist/components/menu/MenuList.svelte.d.ts +30 -0
- package/dist/components/metadata/Metadata.svelte +38 -0
- package/dist/components/metadata/Metadata.svelte.d.ts +31 -0
- package/dist/components/metadata/MetadataRow.svelte +84 -0
- package/dist/components/metadata/MetadataRow.svelte.d.ts +26 -0
- package/dist/components/metadata/index.d.ts +8 -0
- package/dist/components/metadata/index.js +13 -0
- package/dist/components/side-menu/SideMenu.svelte +138 -0
- package/dist/components/side-menu/SideMenu.svelte.d.ts +25 -0
- package/dist/components/side-menu/SideMenuGroup.svelte +108 -0
- package/dist/components/side-menu/SideMenuGroup.svelte.d.ts +31 -0
- package/dist/components/side-menu/SideMenuItem.svelte +221 -0
- package/dist/components/side-menu/SideMenuItem.svelte.d.ts +46 -0
- package/dist/components/side-menu/context.d.ts +1 -0
- package/dist/components/side-menu/context.js +3 -0
- package/dist/components/side-menu/index.d.ts +62 -0
- package/dist/components/side-menu/index.js +15 -0
- package/dist/components/tiles/Tile.svelte +419 -0
- package/dist/components/tiles/Tile.svelte.d.ts +58 -0
- package/dist/components/tiles/TileGroup.svelte +135 -0
- package/dist/components/tiles/TileGroup.svelte.d.ts +45 -0
- package/dist/components/tiles/context.d.ts +35 -0
- package/dist/components/tiles/context.js +14 -0
- package/dist/components/tiles/index.d.ts +6 -0
- package/dist/components/tiles/index.js +13 -0
- package/dist/components/upload/FileCard.svelte +301 -0
- package/dist/components/upload/FileCard.svelte.d.ts +127 -0
- package/dist/components/upload/Thumb.svelte +274 -0
- package/dist/components/upload/Thumb.svelte.d.ts +101 -0
- package/dist/components/upload/UploadFile.svelte +123 -0
- package/dist/components/upload/UploadFile.svelte.d.ts +48 -0
- package/dist/components/upload/UploadFiles.svelte +177 -0
- package/dist/components/upload/UploadFiles.svelte.d.ts +50 -0
- package/dist/components/upload/UploadFolder.svelte +153 -0
- package/dist/components/upload/UploadFolder.svelte.d.ts +63 -0
- package/dist/components/upload/UploadImage.svelte +137 -0
- package/dist/components/upload/UploadImage.svelte.d.ts +52 -0
- package/dist/components/upload/UploadImages.svelte +172 -0
- package/dist/components/upload/UploadImages.svelte.d.ts +52 -0
- package/dist/components/upload/UploadZone.svelte +130 -0
- package/dist/components/upload/UploadZone.svelte.d.ts +41 -0
- package/dist/components/upload/common.d.ts +31 -0
- package/dist/components/upload/common.js +103 -0
- package/dist/components/upload/context.d.ts +18 -0
- package/dist/components/upload/context.js +10 -0
- package/dist/components/upload/index.d.ts +16 -0
- package/dist/components/upload/index.js +18 -0
- package/dist/css/atoms.css +899 -0
- package/dist/css/base.css +334 -0
- package/dist/css/effects.css +430 -0
- package/dist/css/index.css +10 -0
- package/dist/css/tokens.css +296 -0
- package/dist/fonts.d.ts +1 -0
- package/dist/fonts.js +7 -0
- package/dist/index.d.ts +68 -0
- package/dist/index.js +77 -0
- package/dist/lib/announce.d.ts +8 -0
- package/dist/lib/announce.js +48 -0
- package/dist/lib/controls.d.ts +10 -0
- package/dist/lib/controls.js +42 -0
- package/dist/lib/dates.d.ts +104 -0
- package/dist/lib/dates.js +235 -0
- package/dist/lib/dialogs.svelte.d.ts +8 -0
- package/dist/lib/dialogs.svelte.js +45 -0
- package/dist/lib/dom.d.ts +34 -0
- package/dist/lib/dom.js +90 -0
- package/dist/lib/field-errors.svelte.d.ts +40 -0
- package/dist/lib/field-errors.svelte.js +89 -0
- package/dist/lib/files.d.ts +74 -0
- package/dist/lib/files.js +215 -0
- package/dist/lib/inline-md.d.ts +1 -0
- package/dist/lib/inline-md.js +36 -0
- package/dist/lib/invalid.d.ts +4 -0
- package/dist/lib/invalid.js +35 -0
- package/dist/lib/list-search.d.ts +9 -0
- package/dist/lib/list-search.js +27 -0
- package/dist/lib/menu.svelte.d.ts +39 -0
- package/dist/lib/menu.svelte.js +98 -0
- package/dist/lib/morph.svelte.d.ts +17 -0
- package/dist/lib/morph.svelte.js +46 -0
- package/dist/lib/motion.d.ts +115 -0
- package/dist/lib/motion.js +174 -0
- package/dist/lib/observe.d.ts +36 -0
- package/dist/lib/observe.js +142 -0
- package/dist/lib/reveal.d.ts +7 -0
- package/dist/lib/reveal.js +28 -0
- package/dist/lib/roving.d.ts +16 -0
- package/dist/lib/roving.js +35 -0
- package/dist/lib/runs.d.ts +18 -0
- package/dist/lib/runs.js +25 -0
- package/dist/lib/scroll-fade.d.ts +4 -0
- package/dist/lib/scroll-fade.js +71 -0
- package/dist/lib/spotlight.d.ts +4 -0
- package/dist/lib/spotlight.js +109 -0
- package/dist/lib/ticks.d.ts +12 -0
- package/dist/lib/ticks.js +24 -0
- package/dist/lib/tooltip.d.ts +4 -0
- package/dist/lib/tooltip.js +110 -0
- package/dist/lib/validity.d.ts +16 -0
- package/dist/lib/validity.js +36 -0
- package/package.json +69 -3
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Xerios
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,404 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @xerios/design-system
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
A note of warning: This is **designed for personal use and building local web-apps**, so no cross-browser tests have been performed.
|
|
4
|
+
|
|
5
|
+
A Linear-style design system for Svelte 5 apps: theme tokens (light and dark), a global CSS layer, and generic
|
|
6
|
+
components (inputs, menus, popovers, tooltips, collapsibles, toasts). Dense, quiet, keyboard-first.
|
|
7
|
+
|
|
8
|
+
Nothing in it knows about the apps that use it: anything domain-specific stays in the app.
|
|
9
|
+
|
|
10
|
+
Plain JavaScript with JSDoc types, Svelte 5 runes. It ships as Svelte source (compiled by your bundler, like any
|
|
11
|
+
Svelte library) with generated `.d.ts` files, so TypeScript apps get props and helpers checked.
|
|
12
|
+
|
|
13
|
+
## Use it in an app
|
|
14
|
+
|
|
15
|
+
1. Install it (Svelte 5.29+ is a peer dependency):
|
|
16
|
+
|
|
17
|
+
```sh
|
|
18
|
+
pnpm add @xerios/design-system
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Any Svelte 5 setup works: SvelteKit, or Vite with `@sveltejs/vite-plugin-svelte`.
|
|
22
|
+
|
|
23
|
+
2. Load the global layer once, in the entry file (or root `+layout.svelte`), before your own CSS:
|
|
24
|
+
|
|
25
|
+
```js
|
|
26
|
+
import '@xerios/design-system/fonts.js' // Inter + JetBrains Mono, bundled (optional: see Fonts)
|
|
27
|
+
import '@xerios/design-system/css/index.css' // tokens, base, effects, atoms
|
|
28
|
+
import './app.css' // yours, after
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
3. Mount the singletons at the root: `<ContextMenu />` (any `contextMenu` attachment or `MenuButton`; it also keeps
|
|
32
|
+
the browser's drag and right-click menu off controls, see `lib/controls.js`), and if you use them `<Dialogs />` (`alertDialog`, `confirmDialog`, `promptDialog`) and `<Toast … />`.
|
|
33
|
+
4. Import components by name from the package root, `import { Select, Icon } from '@xerios/design-system'`, or by
|
|
34
|
+
path, `import Select from '@xerios/design-system/components/inputs/Select.svelte'` (helpers under `/lib/…`).
|
|
35
|
+
|
|
36
|
+
## What's in the package
|
|
37
|
+
|
|
38
|
+
The source lives in `src/` and is published from `dist/` (the same tree plus `.d.ts` files); import paths leave both
|
|
39
|
+
out (`@xerios/design-system/components/…`). Paths elsewhere in this README are relative to `src/`.
|
|
40
|
+
|
|
41
|
+
```
|
|
42
|
+
css/index.css imports the four files below, in order
|
|
43
|
+
css/tokens.css every token, light and dark
|
|
44
|
+
css/base.css reset, body type, selection rules, scrollbars, links, focus rings, kbd, utilities
|
|
45
|
+
css/effects.css scroll fades, lit edge, corner glow, shine, shell atmosphere, shimmer, spotlight, dialog motion
|
|
46
|
+
css/atoms.css .btn, .icon-btn, .data-table, .count, tones, .label-chip, .chip-btn, .field-label, .label-note, .new-dot, .prose
|
|
47
|
+
components/ generic components (table below)
|
|
48
|
+
components/inputs/ form controls
|
|
49
|
+
components/menu/ the context menu layer
|
|
50
|
+
components/tiles/ tiles and the tile group
|
|
51
|
+
components/metadata/ labelled values (Metadata, Metadata.Row)
|
|
52
|
+
components/filters/ filter rows (FilterBar, FilterBar.Chip, FilterBar.Options)
|
|
53
|
+
components/icons.js the built-in glyphs as SVG strings (generated by scripts/icons.js)
|
|
54
|
+
lib/ dom.js, dialogs.svelte.js, motion.js, scroll-fade.js, validity.js, tooltip.js, field-errors.svelte.js, menu.svelte.js, controls.js, inline-md.js, spotlight.js
|
|
55
|
+
fonts.js bundles the two typefaces
|
|
56
|
+
index.js named exports of everything
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
The repo also holds `kitchensink/` (a private preview app, see Kitchen sink) and `scripts/`; neither is published.
|
|
60
|
+
|
|
61
|
+
## Theme
|
|
62
|
+
|
|
63
|
+
Light by default, dark when the OS asks for it. `<html data-theme="light">` or `data-theme="dark"` overrides
|
|
64
|
+
the OS. To avoid a flash, set the attribute from a small inline script in `index.html` before the page paints
|
|
65
|
+
(`kitchensink/index.html` shows how). Each colour token is one `light-dark(light, dark)` pair, and the theme
|
|
66
|
+
only sets `color-scheme`. A non-colour value that differs by theme can't use `light-dark()`; it would be set per theme.
|
|
67
|
+
|
|
68
|
+
## Tokens
|
|
69
|
+
|
|
70
|
+
All in `css/tokens.css`. Components read tokens only, never raw colours or pixel radii.
|
|
71
|
+
|
|
72
|
+
| Group | Tokens |
|
|
73
|
+
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
74
|
+
| Surfaces, back to front | `--bg` (app frame), `--view-bg` (inset view card), `--surface`, `--surface-2`, `--surface-3`, `--elevated` (floating layers) |
|
|
75
|
+
| Text | `--fg` primary, `--fg-2` secondary, `--muted` tertiary, `--faint` quaternary |
|
|
76
|
+
| Hairlines | `--line`, `--line-strong`, `--line-float` (menus, popovers, dialogs) |
|
|
77
|
+
| Fills (translucent, stack on any surface) | `--fill-1` resting, `--fill-2` hover, `--fill-3` pressed or raised, `--fill-4` active |
|
|
78
|
+
| Control fills (tinted, translucent) | `--control-1` … `--control-4`: the fill scale with a faint brand-hue cast (`--control-hue`), for anything you press, type into or drag, so controls read apart from neutral surfaces |
|
|
79
|
+
| Accent | `--accent` (text, focus, ticks), `--brand` (solid fills), `--accent-ink`, `--accent-soft`, `--accent-line`, `--link` (link text) |
|
|
80
|
+
| Semantic tones | `--success`, `--info`, `--warning`, `--neutral`, `--danger`, each with a `-soft` fill |
|
|
81
|
+
| Elevation | `--shadow-sm`, `--shadow-md`, `--shadow-btn` (raised controls: buttons, select triggers, chosen segments), `--shadow` (floating), `--ring` (focus), `--glass`, `--scrim` |
|
|
82
|
+
| Edges and light | `--edge-hi`, `--edge-r`, `--edge-plateau`, `--edge-grad`, `--edge-grad-float`, `--edge-shadow`, `--shine`, `--glow`, `--grain`, `--raised-edge`, `--raised-base`, `--sunken-shadow`, `--relief-texture`, `--relief-shade`, `--solid-edge` and `--solid-line` (on solid buttons), `--knob`, `--knob-shadow` and `--knob-ring` (Switch and Slider thumbs) |
|
|
83
|
+
| Type | `--font-body`, `--font-display`, `--font-data` (= `--font-mono`), weights `--w-normal` 400, `--w-medium` 510, `--w-semibold` 590. Body is 13px/1.5 |
|
|
84
|
+
| Spacing (4px base) | `--space-1` 4 · `-2` 8 · `-3` 12 · `-4` 16 · `-5` 20 · `-6` 24 · `-8` 32 |
|
|
85
|
+
| Radii | `--r-sm` 6 (chips, keys) · `--r` 8 (rows, fields) · `--r-lg` 10 (cards, popovers) · `--r-xl` 12 (panels, dialogs) · `--r-pill` |
|
|
86
|
+
| Motion | `--dur-fast` 120ms, `--dur` 160ms, `--dur-slow` 240ms, `--ease-out`, `--ease-in`, `--ease-enter` with `--dur-enter` 180ms and `--ease-exit` with `--dur-exit` 200ms (Material 3 standard decelerate/accelerate, used by modals), `--ease-spring` with `--dur-spring` 400ms (a dialog's bounce in) and `--ease-dip` with `--dur-dip` 240ms (its drop and lift away), `--delay-intent` 300ms (how long the pointer rests before something lights up) |
|
|
87
|
+
| Layers, low to high | `--z-sticky`, `--z-header`, `--z-drawer`, `--z-toast`, `--z-menu`, `--z-overlay` |
|
|
88
|
+
| Icons | `--icon-sm` 14, `--icon-md` 16, `--icon-lg` 20 |
|
|
89
|
+
| Layout | `--gutter-l`, `--gutter-r` (16px or the safe-area inset) |
|
|
90
|
+
|
|
91
|
+
Tokens an app may set: `--toast-offset` (how far toasts sit above the bottom edge), `--bleed` (on a container
|
|
92
|
+
of `Collapsible`s: its side padding), `--scroll-fade` (fade height on a scroll area), `--page-inset` (on a page's
|
|
93
|
+
scroll area: its side padding, so separators inside run through it to the edges).
|
|
94
|
+
|
|
95
|
+
**App-specific colours** belong in the app's CSS, built on these. For example, an app naming its own tones:
|
|
96
|
+
|
|
97
|
+
```css
|
|
98
|
+
:root {
|
|
99
|
+
--strong: var(--success);
|
|
100
|
+
--strong-soft: var(--success-soft);
|
|
101
|
+
}
|
|
102
|
+
[data-tone='strong'] {
|
|
103
|
+
--tone: var(--strong);
|
|
104
|
+
--tone-soft: var(--strong-soft);
|
|
105
|
+
}
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
## Global classes
|
|
109
|
+
|
|
110
|
+
| Class / attribute | What it is |
|
|
111
|
+
| ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
112
|
+
| `.btn`, `.btn-primary`, `.btn-small`, `.btn-danger` | Pill button: translucent secondary, solid indigo primary, 24px small, solid red for a destructive action |
|
|
113
|
+
| `.dialog`, `.dialog.confirm`, `.dialog-head`, `.dialog-body`, `.dialog-foot` | Modal `<dialog>` panel (560px; 420px for a question) with a header, scrolling body and footer of actions, lit with the shine and corner glow (its `::before` and `::after`); `--dialog-width` sets another width. `Modal` draws the panel and header for you |
|
|
114
|
+
| `.icon-btn` | 28px ghost circle for an icon; `aria-pressed` and `aria-expanded` are styled |
|
|
115
|
+
| `.linklike` | A button that reads as a link |
|
|
116
|
+
| `kbd` | Key cap |
|
|
117
|
+
| `.data-table` | Wrap a `<table>`: hairline card, 40px rows; `.num` for number columns. For sorting, groups or row menus use the `Table` component |
|
|
118
|
+
| `.label-chip`, `.label-dot` | Hairline label pill led by a coloured dot (`--dot`) or icon; `.icon-only`, `.num` variants; `.suggested` (dashed) for a label proposed but not applied yet |
|
|
119
|
+
| `.chip-btn`, `.chip-btn.outlined` | Interactive pill (Linear's property pills) on a `<button>` or `<a>`: borderless and transparent until hovered, secondary text led by an icon or `.label-dot`; `.outlined` adds the hairline. The clickable counterpart of `.label-chip` |
|
|
120
|
+
| `.suggested` | On a `.label-chip`, `.chip-btn` or `.btn` (or `<Button class="suggested">`): something proposed but not applied yet. Dashed outline and no fill at rest (muted text on a label; a button's text stays clear); a button turns solid on hover and press. A dashed outline on a control means this only |
|
|
121
|
+
| `.count` | Small number pill |
|
|
122
|
+
| `.field-box` | The box a text field draws: sunken (faint fill, inset hairline, shadow inside the top and left edges), focus and invalid states |
|
|
123
|
+
| `.eyebrow`, `.field-label`, `.field-head`, `.label-note` | Section label; label above a form control; a label row with an `InfoTip` after it; a dimmed aside after a label or other text (`(optional)`; fields' `note` prop) |
|
|
124
|
+
| `.prose` | Long-form text (docs, notes, rendered markdown): styles the plain elements inside it, headings h1–h6, links, inline code, `kbd`, `mark`, `abbr`, `del` / `ins`, `sub` / `sup`, lists (nested and `dl`), quotes, code blocks, rules, figures and tables. Space goes above each block, none on the first. Pair with `AnchorHeading` for headings that link to themselves |
|
|
125
|
+
| `.new-dot` | Accent dot for unread or new |
|
|
126
|
+
| `[data-tone="success\|info\|warning\|neutral\|danger"]` | Sets `--tone` and `--tone-soft` on the element |
|
|
127
|
+
| `.edge` | Lit-corner hairline drawn over the element's edge (give it `border: 0`); tune with `--edge-a`, `--edge-b`, `--edge-w`, `--edge-x`, `--edge-y` |
|
|
128
|
+
| `.corner-glow` | Empty decorative `<span aria-hidden="true">` child: soft corner light |
|
|
129
|
+
| `.shine` | A beam of light on the element's edge, drawn on `::after`; tune with `--shine-x`, `--shine-y`, `--edge-w`; set `--shine-r` to the element's radius when it isn't `--r-xl` |
|
|
130
|
+
| `.shell` | App frame atmosphere: lit relief over `--bg` and a top-left corner light (uses `::before`) |
|
|
131
|
+
| `.shimmer` | Working sweep along a pill's hairline (pair with a `Shimmer` label); Select, busy `Button`s and status pills use it |
|
|
132
|
+
| `.sr-only`, `.muted`, `.small`, `.block`, `.nowrap`, `.spacer` | Utilities |
|
|
133
|
+
| `[data-arrow="up\|down"]` | Arrow on a tip pointing at its element; `--arrow-x` places it (the tooltips set both) |
|
|
134
|
+
| `[data-layer-root]` | Mark the app shell so popover scrims stack inside it (see `portalNear`) |
|
|
135
|
+
| `[data-floating]` | Put on a layer portalled to `<body>` so an open `Popover` doesn't treat clicks in it as outside |
|
|
136
|
+
|
|
137
|
+
Every `<dialog>` opened with `showModal()` fades in while scaling down from 120% (180ms, decelerate curve) and leaves by flying 24px down while shrinking to 80% and fading out (200ms, accelerate curve). Scroll containers that float (menus,
|
|
138
|
+
popovers) can't host `.edge`; they paint it as background layers, as described in `css/effects.css`.
|
|
139
|
+
|
|
140
|
+
## Kitchen sink
|
|
141
|
+
|
|
142
|
+
`kitchensink/` (at the repo root) is a small Vite app, separate from the library and never published, that shows
|
|
143
|
+
every token, atom and component in its states, grouped as Actions, Inputs, Overlays, Content, Feedback, Atoms,
|
|
144
|
+
Typography and Foundations (one component each in `kitchensink/src/`, built from `Section` and `Demo`; one `Demo`
|
|
145
|
+
per component, each of its states in a captioned `Case` inside it). Its side menu (`SideMenu`, in a drawer under
|
|
146
|
+
860px) lists the areas with their demo counts, follows the scroll, and switches the theme (system, light, dark).
|
|
147
|
+
Glyphs the demos need beyond the built-in set are registered in `kitchensink/src/icons.js`, as an app would; a name
|
|
148
|
+
left out shows the missing-icon placeholder and a console error.
|
|
149
|
+
|
|
150
|
+
```sh
|
|
151
|
+
pnpm install
|
|
152
|
+
pnpm dev # the kitchen sink, with hot reload
|
|
153
|
+
pnpm build:kitchensink # a static build in kitchensink/dist
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
It imports the library by its package name, exactly as an app does, and its Vite config resolves that name to `src/`
|
|
157
|
+
rather than `dist/`, so an edit to a component shows at once. Check a change there, in both themes, with the keyboard
|
|
158
|
+
and at a narrow width. A new component gets a `Demo`.
|
|
159
|
+
|
|
160
|
+
## Components
|
|
161
|
+
|
|
162
|
+
Each file starts with a comment giving its props and behaviour; that comment is the reference, and a JSDoc `Props`
|
|
163
|
+
typedef types them, so a TypeScript app gets its props checked. Every component that draws one main element passes
|
|
164
|
+
other attributes, `class` and attachments through to it (`<Notice class="spaced" {@attach tooltip('…')}>`): the
|
|
165
|
+
wrapper for display components, the control itself (input, button) for inputs, Popover and Select. In short:
|
|
166
|
+
|
|
167
|
+
| Component | Use it for | Main props |
|
|
168
|
+
| ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
169
|
+
| `Icon` | Any icon (Phosphor regular) | `name`, `size` sm/md/lg, `label` (only if it carries meaning) |
|
|
170
|
+
| `empty/` (`Empty`, `Empty.Error`) | Empty state; `Empty.Error` for a view that failed to load, with a retry (an alert) | `title`, `body`, `level`, `icon`, children for actions; Error: `title`, `message`, `onretry` (may be async), `retryLabel` |
|
|
171
|
+
| `Button` | Every `.btn` / `.icon-btn` with behaviour: an icon, async actions (spinner and `pendingLabel` while the promise runs, presses ignored meanwhile, a rejection's message in a bubble under it), links drawn as buttons | `variant` secondary/primary/danger, `small`, `icon`, `iconOnly` + `label`, `href`, `type`, `onclick` (may return a promise), `pending`, `pendingLabel`, `onerror`, `pressed` (bindable; a toggle) |
|
|
172
|
+
| `ErrorMessage` | Error text: inline, or a dismissible bubble under a control | `message`, `id`, `floating`, `ondismiss` |
|
|
173
|
+
| `Notice` | Inline notice about a standing condition | `tone`, `icon`, children for the text |
|
|
174
|
+
| `Shimmer` | "Working…" text | `text` or children, `active`, `as` |
|
|
175
|
+
| `DashOutline` | A dashed outline over its positioned parent with Linear's spaced dashes (3 on, 3.5 off), for something proposed but not applied yet (a range being picked); can draw one slice of a longer outline so the dashes run on across boxes | none; set `--dash-color`, `--dash-radius`, `--dash-x`, `--dash-width` |
|
|
176
|
+
| `WorkingBorder` | Comets circling a card that's busy | none; set `--radius` |
|
|
177
|
+
| `Breadcrumbs` | The path down to the current page, each level a link back up: carets between levels, the last one the current page, a long path folding its middle levels behind a "…" that shows them in place, long labels cut short with a tooltip | `items` (`label`, `href`, `onclick`, `icon`), `current`, `max`, `label` |
|
|
178
|
+
| `side-menu/` (`SideMenu`, `SideMenu.Group`, `SideMenu.Item`) | App navigation column (Linear's sidebar): a header row with a raised main action, groups that fold under a muted heading, rows with an icon, a count and nested rows, all on shared icon, label and trailing columns | SideMenu: `label`, snippets `header` `actions` `footer`; Group: `title`, `open` (bindable), `ontoggle`; Item: `label`, `href` (else a button), `icon`, `current`, `count`, `trailing`, `open` (bindable), `ontoggle`, children for sub-items |
|
|
179
|
+
| `tiles/` (`Tile`, `Tile.Group`) | A bordered box with a title, icon and any content that the whole of answers the pointer (Prose UI's cards, Carbon's tiles): a link or button (call to action, arrow that nudges on hover), a checkbox (toggled only by its top row, so its content can hold controls), or one option of a group; `Tile.Group` makes one choice (radios, arrow keys) or several (`multiple`) of the tiles in it, in a grid | Tile: `title`, `icon`, `href` (+ `target`, `rel`), `onclick`, `checked` (bindable), `value` (in a group), `cta`, `arrow`, `horizontal`, `disabled`, children for content; Group: `value` (bindable), `label`, `hideLabel`, `info`, `multiple`, `columns`, `disabled`, `onchange` |
|
|
180
|
+
| `metadata/` (`Metadata`, `Metadata.Row`) | Labelled values (Linear's project properties): a label column, as wide as the longest, then each row's values (usually `.chip-btn` pills), wrapping when narrow; a label can be a button. Its labels' text lines up with the content around it | Metadata: children for rows; Row: `label`, `onlabelclick`, `labelTip`, children for the values |
|
|
181
|
+
| `filters/` (`FilterBar`, `FilterBar.Chip`, `FilterBar.Options`) | A row of filters (Linear's view filters): joined chips of field, condition, value and ✕, and a funnel button that adds one. The condition opens a menu of the others; the value opens a panel with its editor: values to tick (with icons, tones and counts, a search field past 8), ready-made days beside a calendar, typed words, or your own. `Chip` is one filter for a row of your own; `Options` (`OptionList`) the tick list, for any panel | FilterBar: `fields` ({ key, label, icon, kind options/date/text/custom, options, operators, plural, presets }), `filters` (bindable, [{ field, op, value }]), `onchange`, `label`, `addLabel`, snippets `panel` `summary`; Chip: `field`, `operator`, `operators`, `onoperator`, `onremove`, `open` (bindable), snippets `value` `panel`; Options: `value` (bindable), `options`, `label`, `multiple`, `search`, `onchange`, `onpick` |
|
|
182
|
+
| `Collapsible` | Section in a panel | `title`, `open` (bindable), `ontoggle`, `count`, `meta`, `info` |
|
|
183
|
+
| `CollapsibleAdvanced` | Collapsible card with status | `title`, `open`, `variant`, `dimmed`, `expandable`, `loading`, snippets `lead` `meta` `end` `actions` |
|
|
184
|
+
| `Splitter` | Resizing a panel | `value`, `min`, `max`, `defaultValue`, `side`, `oninput`, `onchange` |
|
|
185
|
+
| `Popover` | Button that opens a panel | `id`, `label`, `trigger` snippet, `badge`, `dot`, `align`, `placement`, `width`, `scrim`, `open` (bindable) |
|
|
186
|
+
| `Tooltip` | Hover or focus tip around content | `tip` snippet, `focusable` |
|
|
187
|
+
| `InfoTip` | ⓘ button with label/text lines: the place for descriptions and help text | `lines`, `label`, `pinnable` |
|
|
188
|
+
| `AnchorHeading` | A heading with a link to itself after its text, shown on hover or focus, for sharing part of a long page (sized by `.prose` or the app) | `id`, `level` 1–6, `label`, children for the text |
|
|
189
|
+
| `Md` | Inline markdown, no `{@html}` | `text` |
|
|
190
|
+
| `menu/MenuButton` | Visible ⋯ twin of a context menu | `items` (function), `label` |
|
|
191
|
+
| `Table` | Data table in a lit card: sortable columns, collapsible row groups, sticky header, row menu | `columns`, `rows` or `groups`, `key`, `cell` snippet, `sort` and `collapsed` (bindable), `selected`, `onselect`, `rowMenu`, `rowLabel`, `label`, `emptyGroup` |
|
|
192
|
+
| `Canvas` | A canvas that fills its box and draws with a callback at the screen's pixel density: animated each frame (paused off screen, still under reduced motion) or redrawn when its size or the `$state` it reads changes | `draw(ctx, frame)`, `animate`, `running`, `duration`, `fps`, `pixelRatio`, `type`, `options`, `clear`, `label`; bindable `canvas`, `width`, `height`; `redraw()`, `restart()` |
|
|
193
|
+
| `Toast` | The toast stack (app owns the list) | `toasts`, `onhold`, `ondismiss` |
|
|
194
|
+
| `inputs/TextField`, `SearchField`, `TextArea` | Text entry | `value` (bindable), `id`, `label`, `hideLabel`, `placeholder`, `shortcut`, `onenter`, `error`, `info`, native constraints (`required`, `pattern`…); `focus()` |
|
|
195
|
+
| `inputs/FieldLabel` | A field's label with an optional dimmed `note` ("(optional)") and `info` ⓘ; every field draws its label with it |
|
|
196
|
+
| `inputs/Select` | Dropdown | `value` (bindable), `options`, `id`, `label`, `groupActions`, `loading`, `error`, `info`, `ghost` (flat, not raised), `disabled`, `search` (a field narrowing the list; on past 8 options), `searchPlaceholder` |
|
|
197
|
+
| `inputs/Segmented`, `ButtonGroup`, `RadioGroup` | One choice of a few: separate pills; one joined pill; a track with the choice raised on it | `value`, `options`, `label`, `onchange`, `iconOnly`; RadioGroup: `fill`, `pill` |
|
|
198
|
+
| `inputs/TagInput` | A list of short values (names, labels) typed into one field | `value` (bindable array), `id`, `label`, `hideLabel`, `placeholder`, `info`, `error`, `separator`, `normalize`, `validate` |
|
|
199
|
+
| `inputs/Switch` | On/off | `checked` (bindable), `id`, `label`, `hint`; other props and attachments go to the button |
|
|
200
|
+
| `inputs/Slider` | Number in a range | `value` (bindable), `min`, `max`, `step`, `id`, `label`, `format`, `ticks` (a mark per stop; `'auto'`: 3 to 11 stops) |
|
|
201
|
+
| `inputs/RangeSlider` | A range of numbers: two thumbs on one track that can't cross | `value` (bindable `[from, to]`), `min`, `max`, `step`, `gap`, `id`, `label`, `format`, `ticks` |
|
|
202
|
+
| `inputs/DatePicker`, `DateRangePicker` | A day, or a span of days: typed as DD/MM/YYYY (or ISO), or picked from a calendar under the field (ISO days, `lib/dates.js`); the range has a from and a to input, or takes two presses, and ready-made spans (Last 7 days…) beside the calendar | `value` (bindable: `'2026-11-18'`, or `[from, to]`), `id`, `label`, `min`, `max`, `allowed` (DatePicker: the only days allowed), `shortcuts` (DateRangePicker), `placeholder`, `clearable`, `error`, `info`, `hideLabel`, `disabled` |
|
|
203
|
+
| `inputs/DateRangeSelect` | A compact span between two of a given list of days or moments (irregular runs): a button opening the list, newest first, picked with two presses, and shortcuts (Most recent, Last 3, This month) | `value` (bindable: `[from, to]`), `dates`, `id`, `label`, `shortcuts`, `placeholder`, `error`, `info`, `hideLabel`, `disabled` |
|
|
204
|
+
| `inputs/Calendar`, `inputs/DateField`, `inputs/DateInput`, `inputs/RangeShortcuts`, `inputs/ListSearch` | The parts the pickers are made of (a month grid; the field and its panel; the shortcut buttons; the search field at the top of Select's and OptionList's lists), for a picker of your own | see their header comments |
|
|
205
|
+
| `upload/` (`Upload.File`, `.Files`, `.Folder`, `.Image`, `.Images`) | File pickers that take drops too. The button becomes what it picked: a card with the name and size (a folder's file count), or a square thumbnail for an image, with a ✕ to clear it; the plural ones list their files (cards, or a grid of thumbnails) above a button that adds more | `file` / `files` / `folder` (bindable), `onchange`, `label`, `accept`, `id`, `disabled`, `error`; `Files`: `addLabel`; `Image`, `Images`: `maxSize` (bytes, default 10 MB) |
|
|
206
|
+
| `upload/UploadZone` (`Upload.Zone`) | A larger place to drop files for the Upload inside it: a dashed area with a hint, or with `bare` any area (a card, a dialog's body), covered by a drop overlay only while files are over it | `bare`, `hint` (default: the Upload's own, such as "Drop images here"), children |
|
|
207
|
+
| `menu/ContextMenu` | The menu layer; mount once | none |
|
|
208
|
+
| `Dialogs` | The layer for `alertDialog`, `confirmDialog` and `promptDialog`; mount once | none |
|
|
209
|
+
| `Modal` | A modal dialog of your own (forms, multi-step flows, a question with more than OK and Cancel): the panel, its header and ✕, backdrop and Esc wiring; body and footer are children | `title`, `narrow`, `closeButton`, `locked`, `canClose`, `onclose`; `show()`, `requestClose()`, `close()`, `isOpen()`; `--dialog-width` |
|
|
210
|
+
| `Drawer` | A side sheet (modal dialog along the window's edge) for details or a longer form beside the page; resizable by its inner edge | `label`, `side`, `width` (bindable, `undefined` = default), `defaultWidth`, `minWidth`, `resizable`, `onresize`, `canClose`, `locked`, `onclose`; `show()`, `requestClose()`, `close()`, `isOpen()` |
|
|
211
|
+
|
|
212
|
+
Option shape for `Select`, `Segmented`, `ButtonGroup`, `RadioGroup` and `OptionList`: `{ value, label, icon?, hint? }`, plus `text`
|
|
213
|
+
and `group` for `Select`, `done` for `Segmented`, `info` for `RadioGroup`, `tone` for `OptionList`.
|
|
214
|
+
|
|
215
|
+
### Icons
|
|
216
|
+
|
|
217
|
+
`Icon` ships about forty general-purpose glyphs (carets, check, x, search, more, undo, eye, gear, sun, moon…;
|
|
218
|
+
`iconNames()` lists them). An app registers the rest once, before it mounts:
|
|
219
|
+
|
|
220
|
+
```js
|
|
221
|
+
import { registerIcons } from '@xerios/design-system'
|
|
222
|
+
import trophy from '@phosphor-icons/core/regular/trophy.svg?raw' // add @phosphor-icons/core to the app
|
|
223
|
+
registerIcons({ trophy })
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
One family, regular weight. The `?raw` import is Vite's; elsewhere pass the SVG markup as a string. The built-in set
|
|
227
|
+
is listed in `scripts/icons.js`: add a glyph there and run `pnpm icons` to regenerate `components/icons.js`.
|
|
228
|
+
|
|
229
|
+
A name nobody registered draws a question mark in the danger colour and logs a console error (once per name), so a
|
|
230
|
+
missing glyph is visible rather than a blank gap. `hasIcon(name)` tells whether a name is registered.
|
|
231
|
+
|
|
232
|
+
### Context menus
|
|
233
|
+
|
|
234
|
+
```svelte
|
|
235
|
+
<ContextMenu />
|
|
236
|
+
<!-- once, at the root -->
|
|
237
|
+
|
|
238
|
+
<li {@attach contextMenu(() => rowMenu(row), 'Row actions')}>
|
|
239
|
+
…
|
|
240
|
+
<MenuButton items={() => rowMenu(row)} label={row.name} />
|
|
241
|
+
</li>
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
Where text can't be selected (base.css: buttons, lists, menus, pickers, labels), the mounted layer also cancels the
|
|
245
|
+
browser's drag and right-click menu. Content, toasts, alerts, text fields and links keep theirs; Shift + right-click always
|
|
246
|
+
gets the browser's menu. To make a component's own chrome behave this way, give it `user-select: none`; to keep a part
|
|
247
|
+
selectable, `user-select: text`.
|
|
248
|
+
|
|
249
|
+
Items: `{ label, icon?, action?, href?, hint?, checked?, toggle?, disabled?, danger?, children? }` or `{ separator: true }`. `icon` sits in
|
|
250
|
+
the column on the left (a checked item shows its check there instead). A `toggle` item shows `checked` as a switch on the right;
|
|
251
|
+
pressing it flips the switch, calls `action(on)` with the new state and leaves the menu open.
|
|
252
|
+
Right-click, Shift+F10 and the Menu key open it; text fields keep the browser's menu. Always pair a context
|
|
253
|
+
menu with a `MenuButton`, so nothing is reachable by right-click only.
|
|
254
|
+
|
|
255
|
+
### Modal
|
|
256
|
+
|
|
257
|
+
```svelte
|
|
258
|
+
<Modal bind:this={modal} title="New site" canClose={confirmDiscard} onclose={reset}>
|
|
259
|
+
<form id="new-site" class="dialog-body" novalidate onsubmit={submit}>…</form>
|
|
260
|
+
<footer class="dialog-foot">
|
|
261
|
+
<span class="spacer"></span>
|
|
262
|
+
<button type="button" class="btn" onclick={() => modal.requestClose()}>Cancel</button>
|
|
263
|
+
<button type="submit" form="new-site" class="btn btn-primary">Create</button>
|
|
264
|
+
</footer>
|
|
265
|
+
</Modal>
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
```js
|
|
269
|
+
// Every way of closing (✕, Esc, backdrop, requestClose) asks this first; false keeps it open.
|
|
270
|
+
async function confirmDiscard() {
|
|
271
|
+
if (!dirty) return true
|
|
272
|
+
return confirmDialog({ title: 'Discard this site?', confirmLabel: 'Discard', cancelLabel: 'Keep editing', danger: true })
|
|
273
|
+
}
|
|
274
|
+
```
|
|
275
|
+
|
|
276
|
+
`locked` holds it open (✕ disabled) while work it shows has to finish; `close()` still closes it. The children are
|
|
277
|
+
the body and footer, so each step of a flow can swap them. Other attributes and attachments go to the `<dialog>`.
|
|
278
|
+
|
|
279
|
+
### Alert, confirm and prompt
|
|
280
|
+
|
|
281
|
+
Promise-based stand-ins for the browser's, in a `.dialog.confirm` above whatever dialog is open (a form under it
|
|
282
|
+
keeps its state). Mount `<Dialogs />` once; requests made while one shows wait their turn.
|
|
283
|
+
|
|
284
|
+
```js
|
|
285
|
+
await alertDialog({ title: 'Upload failed', body: 'The file is over 50 MB.' })
|
|
286
|
+
if (await confirmDialog({ title: 'Discard changes?', confirmLabel: 'Discard', cancelLabel: 'Keep editing', danger: true })) close()
|
|
287
|
+
const name = await promptDialog({ title: 'Rename', label: 'Name', value: old, validate: v => (v.trim() ? '' : 'Enter a name') })
|
|
288
|
+
```
|
|
289
|
+
|
|
290
|
+
A string is taken as the title. Esc, a backdrop click and cancel answer `undefined` / `false` / `null`. `danger`
|
|
291
|
+
makes the confirm button red and starts the focus on cancel. A prompt's `validate` runs on confirm only.
|
|
292
|
+
|
|
293
|
+
### Toast
|
|
294
|
+
|
|
295
|
+
```js
|
|
296
|
+
// app state: oldest first, newest last
|
|
297
|
+
const timers = new Map()
|
|
298
|
+
let held = false
|
|
299
|
+
const arm = ({ id, ms }) =>
|
|
300
|
+
timers.set(
|
|
301
|
+
id,
|
|
302
|
+
setTimeout(() => dismiss(id), ms),
|
|
303
|
+
)
|
|
304
|
+
export function toast(message, action = null, ms = 5000) {
|
|
305
|
+
const t = { id: crypto.randomUUID(), message, action, ms }
|
|
306
|
+
app.toasts.push(t)
|
|
307
|
+
if (!held) arm(t)
|
|
308
|
+
}
|
|
309
|
+
export function dismiss(id) {
|
|
310
|
+
clearTimeout(timers.get(id))
|
|
311
|
+
timers.delete(id)
|
|
312
|
+
app.toasts = app.toasts.filter(t => t.id !== id)
|
|
313
|
+
}
|
|
314
|
+
export function hold(on) {
|
|
315
|
+
held = on
|
|
316
|
+
for (const timer of timers.values()) clearTimeout(timer)
|
|
317
|
+
timers.clear()
|
|
318
|
+
if (!on) app.toasts.forEach(arm)
|
|
319
|
+
}
|
|
320
|
+
```
|
|
321
|
+
|
|
322
|
+
```svelte
|
|
323
|
+
<Toast toasts={app.toasts} onhold={hold} ondismiss={dismiss} />
|
|
324
|
+
```
|
|
325
|
+
|
|
326
|
+
The newest toast is in front with up to two older ones peeking out behind it; hovering or focusing the stack fans it
|
|
327
|
+
out and holds every timer.
|
|
328
|
+
|
|
329
|
+
## Helpers (`lib/`)
|
|
330
|
+
|
|
331
|
+
| Export | What it does |
|
|
332
|
+
| ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
333
|
+
| `portal`, `portalNear(from)` | Attachments that move a node to `<body>` or the nearest `[data-layer-root]` |
|
|
334
|
+
| `announce(text, { delay? })`, `cancelAnnouncement()` | The page's one polite live region (moved into the open modal, since outside it is inert). `fieldErrors` uses it for an error that appears as a field is left; `TagInput` for tags added, removed or refused |
|
|
335
|
+
| `invalid(errorId)` | Attachment: `aria-invalid` ("true", else "false") and the message's id in `aria-describedby` on a control or group, every field alike. `FIRST_INVALID`: the selector for the control to focus after a failed submit |
|
|
336
|
+
| `dates` | ISO day helpers for pickers: `parse`, `today`, `addDays`, `addMonths`, `monthGrid`, `formatDay`, `within`, `clamp`…; `relativeDay('-3d')` and `datePresets()` for relative days (a date filter's value) |
|
|
337
|
+
| `composing(event)` | True while a key belongs to an IME composition (`isComposing`, or `keyCode` 229 for Safari): return early from a field's own Enter / Esc / Backspace handling |
|
|
338
|
+
| `radioKeys` | Attachment for a `role="radiogroup"` with roving focus: arrows, Home and End move to an option and choose it (what `Segmented`, `ButtonGroup` and `RadioGroup` use) |
|
|
339
|
+
| `topLayer(from)` | Attachment that shows a floating node in the top layer, above modal dialogs (inside the dialog around `from`, else `<body>`) |
|
|
340
|
+
| `backdropClose(close)` | Handlers to spread on a `<dialog>`: closes on a true backdrop click only |
|
|
341
|
+
| `closeRequests(request)` | Handlers to spread on a `<dialog>` that must ask before closing: Esc (however fast it is repeated) and other close requests call `request` instead of closing |
|
|
342
|
+
| `fade`, `fly`, `slide`, `scale` | Svelte's transitions on Material 3's motion rules: decelerate curve going in (250ms), accelerate going out (200ms), 0ms under reduced motion. Extra params `emphasized` (the emphasized set, for transitions that should draw the eye: 400ms in, 200ms out), `duration` (ms, both ways) and `curve: 'standard'` (one curve both ways, 300ms; `slide`'s default) |
|
|
343
|
+
| `pop({ from?, start?, distance?, duration? })` | For a small floating layer (list, menu, tip, panel): fades while growing from 97% out of `from` (an element or `{ x, y }`) and moving 4px away from it, on whichever side it ended up; 150ms in, 100ms out, 0ms under reduced motion. `<ul transition:pop={{ from: button }}>` |
|
|
344
|
+
| `flip` | `animate:flip` on the standard curve, 300ms by default |
|
|
345
|
+
| `tween(value, { emphasized?, duration? })` | A `Tween` from `svelte/motion` on the standard curve, for a value that changes in place |
|
|
346
|
+
| `durations`, `easings`, `defaults` | Material 3's duration tokens (`short1` 50 … `extraLong4` 1000), curves (`easings.standard.decelerate` and so on) and each curve's usual duration, for custom transitions |
|
|
347
|
+
| `motion(ms)` | Duration for a custom transition; 0 under reduced motion (`prefersReducedMotion` from `svelte/motion`) |
|
|
348
|
+
| `scrollFade({ size? })` | Attachment: fades a scroll area's top and bottom edges while there is more to scroll |
|
|
349
|
+
| `observeSize(el, cb, { box? })`, `observeVisibility(el, cb, { rootMargin?, threshold? })` | One shared ResizeObserver / IntersectionObserver for every element instead of one each; `cb` gets the element's latest entry, also on subscribing. Returns the stop function (return it from an attachment) |
|
|
350
|
+
| `fileDrop({ ondrop, ondragging?, disabled? })` | Attachment: a drop target for files and folders (`data-dragging` while they are over it); `ondrop` gets what `dropped(dataTransfer)` reads |
|
|
351
|
+
| `filesOfDrop(drop)`, `droppedFiles(drop)`, `filesUnder(entry)` | A drop's files with their paths (one folder: paths inside it, and its name); its loose files without folders; every file under a dropped entry |
|
|
352
|
+
| `accepts(file, accept)`, `fileSize(bytes)`, `preview(file)` | Whether a file fits an `accept` list (for drops, which skip the picker's filter); a size for display; an attachment showing a file in an `<img>` through an object URL it revokes |
|
|
353
|
+
| `morph(node, key)` | Call during init: animates the element's width and height when `key` changes, so it reshapes into its new content (what Upload's button does) |
|
|
354
|
+
| `fieldErrors(validate)` | A form's error messages with submit-first timing (nothing shows until `validate()`, then fields recheck on blur): `{...form.field('name')}` on a text field, `{@attach form.group('name')}` on a wrapper, `form.validate()` on submit |
|
|
355
|
+
| `wantsSearch(search, count)`, `matches(text, query)` | When a list gets a search field (`'auto'`: past `SEARCH_AFTER`, 8, options) and what a typed query matches (anywhere, ignoring case and accents): what Select and OptionList share |
|
|
356
|
+
| `reveal(list, item)` | Scrolls a list's keyboard option into view, clear of the list's padding and of its group's sticky heading (`[data-sticky-head]` in the `[role="group"]` around it), measured rather than a fixed `scroll-padding`: what Select, DateRangeSelect and OptionList use |
|
|
357
|
+
| `tooltip(text, { shortcut?, detail? })` | Attachment: tooltip on hover and keyboard focus, above dialogs too. Required on icon-only buttons and terse toggles. `detail`: a second line under the bold text (a full file name) |
|
|
358
|
+
| `validity(error, report)` | Attachment: ties an `<input>` or `<textarea>` to the browser's constraint validation (what the `error` prop of the text fields uses) |
|
|
359
|
+
| `contextMenu`, `menu`, `openMenu`, `openMenuFrom`, `closeMenu` | Context menu state and attachment |
|
|
360
|
+
| `alertDialog`, `confirmDialog`, `promptDialog` | Promise-based alert, confirm and prompt, drawn by `<Dialogs />` |
|
|
361
|
+
| `inlineMd(text)` | Parses inline markdown into parts (what `Md` renders) |
|
|
362
|
+
| `spotlight(id, { timeout? })` | Waits for the element with that id (or the collapsed toggle whose `aria-controls` names it) to appear, reveals it (clicks the toggle, opens a closed `<details>` around it), scrolls to it and flashes it briefly. Call it right after opening what holds it. Resolves to the element or null |
|
|
363
|
+
|
|
364
|
+
## Fonts
|
|
365
|
+
|
|
366
|
+
`fonts.js` bundles Inter and JetBrains Mono (variable), so nothing loads from the network. To use other faces,
|
|
367
|
+
skip the import and set `--font-body`, `--font-display` and `--font-data` in your CSS; the weights 510 and 590
|
|
368
|
+
assume a variable font.
|
|
369
|
+
|
|
370
|
+
## Conventions the system relies on
|
|
371
|
+
|
|
372
|
+
- Breakpoint: one, at 860px. Below it `Splitter` hides, popovers span the width and fields grow to 16px text.
|
|
373
|
+
- Text sizes are in px. Boxes that hold text take a `min-height`, not a fixed `height`, so a label that wraps grows the
|
|
374
|
+
box instead of spilling out of it.
|
|
375
|
+
- Reduced motion: CSS animations stop and transitions keep only colour changes (nothing moves, scales or loops), globally; Svelte transitions come from `lib/motion.js` (or take `motion(ms)`).
|
|
376
|
+
- Accessibility: every text and background pair meets WCAG AA in both themes; pointer targets are at least
|
|
377
|
+
24×24px; focus rings come from `:focus-visible` in `base.css`.
|
|
378
|
+
- Contrast settings: with `prefers-contrast: more` the hairlines, scrollbar and quiet text tokens strengthen (boundaries
|
|
379
|
+
3:1, `--muted`/`--faint` text 4.5:1, both themes; `tokens.css`). In forced colours (Windows High Contrast) the
|
|
380
|
+
shadows and gradients that draw field boxes, focus rings, floating edges and chosen states are replaced by
|
|
381
|
+
outlines, borders and system-colour fills (`base.css`). A new component that marks state or an edge only with a
|
|
382
|
+
shadow, gradient or fill adds its own forced-colours rule.
|
|
383
|
+
- Browser support: current Chromium, Firefox and Safari (`color-mix()`, `@property`, `@starting-style`,
|
|
384
|
+
`offset-path`, Svelte 5.29+ for `{@attach}`).
|
|
385
|
+
|
|
386
|
+
## Developing and publishing
|
|
387
|
+
|
|
388
|
+
```sh
|
|
389
|
+
pnpm install
|
|
390
|
+
pnpm dev # kitchen sink on the live source
|
|
391
|
+
pnpm build # svelte-package: src/ → dist/ with .d.ts files, then publint checks the package
|
|
392
|
+
pnpm icons # regenerate components/icons.js after editing scripts/icons.js
|
|
393
|
+
```
|
|
394
|
+
|
|
395
|
+
To release: bump `version` in `package.json` (a renamed or removed token, class, prop or export is a breaking change),
|
|
396
|
+
then `pnpm publish`. `prepack` rebuilds `dist/` first, and only `dist/`, this README and the license are published.
|
|
397
|
+
|
|
398
|
+
To try an unreleased build in an app, link it (`"@xerios/design-system": "link:../design-system"`) and run
|
|
399
|
+
`pnpm build` here after each change, or `pnpm pack` and install the tarball.
|
|
400
|
+
|
|
401
|
+
## Adding to it
|
|
402
|
+
|
|
403
|
+
See `CLAUDE.md` in the repo for the rules (they apply to people as well). The test for whether something
|
|
404
|
+
belongs here: could a different app use it without changing it?
|