svelte-ant-design 0.2.1 → 0.3.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/README.md CHANGED
@@ -18,7 +18,7 @@ Ant Design.
18
18
 
19
19
  ## Status
20
20
 
21
- Version `0.2.1`. Available components: `Button`, `Switch`. More components are planned.
21
+ Version `0.3.0`. Available components: `Button`, `Checkbox` (with `CheckboxGroup`), `Switch`. More components are planned.
22
22
 
23
23
  ## Installation
24
24
 
@@ -49,24 +49,26 @@ Import components by name. The package is ESM and declares `sideEffects: ["**/*.
49
49
  bundler that supports tree shaking leaves out the components you do not use. This is checked with
50
50
  Vite in `tests/packaging`; other bundlers are not covered.
51
51
 
52
- See the [Button](https://prostreyd.github.io/ant-design-svelte/components/button/) and
52
+ See the [Button](https://prostreyd.github.io/ant-design-svelte/components/button/),
53
+ [Checkbox](https://prostreyd.github.io/ant-design-svelte/components/checkbox/) and
53
54
  [Switch](https://prostreyd.github.io/ant-design-svelte/components/switch/) pages of the documentation site for
54
- examples and the API tables, or [`src/lib/Button/README.md`](./src/lib/Button/README.md) and
55
+ examples and the API tables, or [`src/lib/Button/README.md`](./src/lib/Button/README.md),
56
+ [`src/lib/Checkbox/README.md`](./src/lib/Checkbox/README.md) and
55
57
  [`src/lib/Switch/README.md`](./src/lib/Switch/README.md) in the repository.
56
58
 
57
59
  ### Colors and contrast
58
60
 
59
61
  In the light theme the colors are the values of the Ant Design token documentation, so the components look
60
62
  like Ant Design. Those values do not reach WCAG AA for text: white on the primary fill is 4.10:1 and on the
61
- danger fill 3.27:1 (4.5:1 is needed), and the off track of a switch is 1.84:1 against a white page (3:1 is
62
- needed). For a contrast guarantee import one more file after the tokens:
63
+ danger fill 3.27:1 (4.5:1 is needed), the off track of a switch is 1.84:1 against a white page and the border of
64
+ an unchecked checkbox 1.41:1 (3:1 is needed). For a contrast guarantee import one more file after the tokens:
63
65
 
64
66
  ```ts
65
67
  import 'svelte-ant-design/tokens.css';
66
68
  import 'svelte-ant-design/tokens-accessible.css';
67
69
  ```
68
70
 
69
- It darkens the fills, the link and text colors and the switch tracks; every text pair is then at least 4.5:1.
71
+ It darkens the fills, the link and text colors, the switch tracks and the checkbox border; every text pair is then at least 4.5:1.
70
72
  The dark theme needs no extra file. The contrast tests run with the accessible file.
71
73
 
72
74
  ### Dark theme
@@ -0,0 +1,324 @@
1
+ <script lang="ts">
2
+ import { onDestroy, type Snippet } from 'svelte';
3
+ import type { HTMLInputAttributes } from 'svelte/elements';
4
+ import type { CheckboxClassNames, CheckboxStyles, CheckboxValue } from './types.js';
5
+ import { getCheckboxGroup } from './context.js';
6
+ import { isProduction } from '../internal/env.js';
7
+ import { classList, styleText } from '../internal/semantic.js';
8
+
9
+ type CheckboxProps = Omit<
10
+ HTMLInputAttributes,
11
+ | 'children'
12
+ | 'class'
13
+ | 'style'
14
+ | 'type'
15
+ | 'checked'
16
+ | 'indeterminate'
17
+ | 'value'
18
+ | 'disabled'
19
+ | 'name'
20
+ | 'title'
21
+ | 'onchange'
22
+ > & {
23
+ /**
24
+ * Whether the checkbox is checked. Use `bind:checked` for two-way binding. Inside a
25
+ * `CheckboxGroup` the state comes from the group's `value` and this prop is ignored.
26
+ */
27
+ checked?: boolean;
28
+ /**
29
+ * The "partly checked" look of a "check all" control. It changes only the appearance and the
30
+ * state assistive technology reads (`mixed`); `checked` stays the value that is reported.
31
+ */
32
+ indeterminate?: boolean;
33
+ /** Whether the checkbox is disabled. A group's `disabled` applies as well. */
34
+ disabled?: boolean;
35
+ /** Identity inside a `CheckboxGroup` and the native `value` of the input. */
36
+ value?: CheckboxValue;
37
+ /** Native `name` of the input. Inside a group the group's `name` wins. */
38
+ name?: string;
39
+ /** Label content; it is the accessible name of the checkbox. */
40
+ children?: Snippet;
41
+ /** Called once per user toggle, after the state changed, with the new value and the native `change` event. */
42
+ onchange?: (checked: boolean, event: Event) => void;
43
+ /** Extra classes for the `root`, `icon` and `label` parts. */
44
+ classNames?: CheckboxClassNames;
45
+ /** Inline styles for the `root`, `icon` and `label` parts. */
46
+ styles?: CheckboxStyles;
47
+ /** Additional CSS class appended to the root classes. */
48
+ class?: string;
49
+ /** Inline style of the root; `styles.root` is applied after it. */
50
+ style?: string;
51
+ /** Native `title` of the root label, so the tooltip covers the box and the text. */
52
+ title?: string;
53
+ };
54
+
55
+ let {
56
+ checked = $bindable(false),
57
+ indeterminate = false,
58
+ disabled = false,
59
+ value = undefined,
60
+ name = undefined,
61
+ children,
62
+ onchange,
63
+ classNames,
64
+ styles,
65
+ class: customClass,
66
+ style: customStyle,
67
+ title = undefined,
68
+ ...rest
69
+ }: CheckboxProps = $props();
70
+
71
+ const group = getCheckboxGroup();
72
+
73
+ // A checkbox takes part in its group only with a value: the group tells the items apart by it.
74
+ // Without one it keeps its own state (and throws while developing, so the mistake is found early).
75
+ const member = $derived.by(() => {
76
+ if (!group) return false;
77
+ if (value !== undefined) return true;
78
+ if (!isProduction()) throw new TypeError('Checkbox inside a CheckboxGroup needs a value.');
79
+ return false;
80
+ });
81
+
82
+ // Registered in the order of mounting, which is the order of the values of the group.
83
+ if (group) onDestroy(group.register(() => value));
84
+
85
+ let input: HTMLInputElement | undefined = $state();
86
+
87
+ const isChecked = $derived(member ? group!.isChecked(value!) : checked);
88
+ const isDisabled = $derived(disabled || Boolean(group?.disabled));
89
+ const inputName = $derived(group?.name ?? name);
90
+
91
+ const rootClass = $derived(
92
+ classList(
93
+ 'ads-checkbox',
94
+ isChecked && 'ads-checkbox-checked',
95
+ indeterminate && 'ads-checkbox-indeterminate',
96
+ isDisabled && 'ads-checkbox-disabled',
97
+ customClass,
98
+ classNames?.root,
99
+ group?.classNames?.item
100
+ )
101
+ );
102
+ const iconClass = $derived(classList('ads-checkbox-icon', classNames?.icon, group?.classNames?.itemIcon));
103
+ const labelClass = $derived(
104
+ classList('ads-checkbox-label', classNames?.label, group?.classNames?.itemLabel)
105
+ );
106
+
107
+ const rootStyle = $derived(styleText(group?.styles?.item, customStyle, styles?.root));
108
+ const iconStyle = $derived(styleText(group?.styles?.itemIcon, styles?.icon));
109
+ const labelStyle = $derived(styleText(group?.styles?.itemLabel, styles?.label));
110
+
111
+ // A native form reset puts the input back to its default checkedness behind the state's back (it leaves
112
+ // `indeterminate` alone). The state is the truth (the parent resets it in `onreset`), so the view is
113
+ // restored to it once the reset has run.
114
+ $effect(() => {
115
+ const form = input?.form;
116
+ if (!form) return;
117
+ const restore = () => {
118
+ setTimeout(() => {
119
+ if (!input) return;
120
+ input.checked = isChecked;
121
+ });
122
+ };
123
+ form.addEventListener('reset', restore);
124
+ return () => form.removeEventListener('reset', restore);
125
+ });
126
+
127
+ function handleChange(event: Event): void {
128
+ const target = event.currentTarget as HTMLInputElement;
129
+ const next = target.checked;
130
+ if (member) {
131
+ onchange?.(next, event);
132
+ group!.toggle(value!, next, event);
133
+ } else {
134
+ checked = next;
135
+ onchange?.(next, event);
136
+ }
137
+ // The input owns its state. Writing the props back reverts a change the parent refused
138
+ // (function binding) and restores the indeterminate flag, which the browser clears on a click.
139
+ target.checked = isChecked;
140
+ target.indeterminate = indeterminate;
141
+ }
142
+
143
+ /** Moves focus to the checkbox. */
144
+ export function focus(options?: FocusOptions): void {
145
+ input?.focus(options);
146
+ }
147
+
148
+ /** Removes focus from the checkbox. */
149
+ export function blur(): void {
150
+ input?.blur();
151
+ }
152
+ </script>
153
+
154
+ <!--
155
+ A native input inside a label: the role, the checked and mixed states, Space, the Tab order, the
156
+ click on the text and form participation come from the platform. The input is laid over the
157
+ box, invisible, so the focus ring and the hit area are those of a real control.
158
+ -->
159
+ <label class={rootClass} style={rootStyle} {title}>
160
+ <span class="ads-checkbox-control">
161
+ <input
162
+ {...rest}
163
+ bind:this={input}
164
+ type="checkbox"
165
+ class="ads-checkbox-input"
166
+ checked={isChecked}
167
+ {indeterminate}
168
+ disabled={isDisabled}
169
+ name={inputName}
170
+ value={value ?? 'on'}
171
+ onchange={handleChange}
172
+ />
173
+ <span class={iconClass} style={iconStyle} aria-hidden="true"></span>
174
+ </span>
175
+ {#if children}
176
+ <span class={labelClass} style={labelStyle}>{@render children()}</span>
177
+ {/if}
178
+ </label>
179
+
180
+ <style>
181
+ /*
182
+ * The states only set the private `--_*` variables; the rules that paint the box read them, so
183
+ * checked, indeterminate, hover and disabled combine without fighting over specificity. The
184
+ * colors come from the `--ads-checkbox-*` tokens. Positions use logical properties, so the
185
+ * checkbox mirrors in right-to-left layouts.
186
+ */
187
+ .ads-checkbox {
188
+ --_size: var(--ads-checkbox-size);
189
+ --_border: var(--ads-checkbox-border);
190
+ --_bg: var(--ads-checkbox-bg);
191
+ --_mark: var(--ads-checkbox-check-color);
192
+ --_bar: var(--ads-checkbox-indeterminate-color);
193
+
194
+ position: relative;
195
+ display: inline-flex;
196
+ align-items: flex-start;
197
+ box-sizing: border-box;
198
+ margin: 0;
199
+ color: var(--ads-color-text);
200
+ font-family: var(--ads-font-family);
201
+ font-size: var(--ads-checkbox-font-size);
202
+ line-height: var(--ads-checkbox-line-height);
203
+ cursor: pointer;
204
+ }
205
+
206
+ .ads-checkbox-control {
207
+ position: relative;
208
+ flex: none;
209
+ width: var(--_size);
210
+ height: var(--_size);
211
+ /* Centered in the first line of the text, so a multi-line label keeps the box at the top. */
212
+ margin-block: calc(
213
+ (var(--ads-checkbox-line-height) * var(--ads-checkbox-font-size) - var(--_size)) / 2
214
+ );
215
+ }
216
+
217
+ .ads-checkbox-input {
218
+ position: absolute;
219
+ inset: 0;
220
+ z-index: 1;
221
+ box-sizing: border-box;
222
+ width: 100%;
223
+ height: 100%;
224
+ margin: 0;
225
+ padding: 0;
226
+ opacity: 0;
227
+ cursor: inherit;
228
+ }
229
+
230
+ .ads-checkbox-icon {
231
+ position: absolute;
232
+ inset: 0;
233
+ box-sizing: border-box;
234
+ border: var(--ads-checkbox-border-width) solid var(--_border);
235
+ border-radius: var(--ads-checkbox-radius);
236
+ background-color: var(--_bg);
237
+ transition:
238
+ border-color var(--ads-motion-duration-fast) var(--ads-motion-ease),
239
+ background-color var(--ads-motion-duration-fast) var(--ads-motion-ease);
240
+ }
241
+
242
+ /* The check mark is a rotated corner, drawn with borders; the indeterminate bar reuses the same box. */
243
+ .ads-checkbox-icon::after {
244
+ content: '';
245
+ position: absolute;
246
+ top: 50%;
247
+ left: 50%;
248
+ box-sizing: border-box;
249
+ width: calc(var(--_size) * 0.3125);
250
+ height: calc(var(--_size) * 0.5625);
251
+ border: solid var(--_mark);
252
+ border-width: 0 var(--ads-checkbox-check-width) var(--ads-checkbox-check-width) 0;
253
+ transform: translate(-50%, -58%) rotate(45deg) scale(0);
254
+ opacity: 0;
255
+ transition:
256
+ opacity var(--ads-motion-duration-fast) var(--ads-motion-ease),
257
+ transform var(--ads-motion-duration-slow) var(--ads-motion-ease-out-back);
258
+ }
259
+
260
+ .ads-checkbox-checked .ads-checkbox-icon {
261
+ --_border: var(--ads-checkbox-checked-bg);
262
+ --_bg: var(--ads-checkbox-checked-bg);
263
+ }
264
+
265
+ .ads-checkbox-checked .ads-checkbox-icon::after {
266
+ transform: translate(-50%, -58%) rotate(45deg) scale(1);
267
+ opacity: 1;
268
+ }
269
+
270
+ /* The bar replaces the check mark whatever the checked state. */
271
+ .ads-checkbox-indeterminate .ads-checkbox-icon {
272
+ --_border: var(--ads-checkbox-border);
273
+ --_bg: var(--ads-checkbox-bg);
274
+ }
275
+
276
+ .ads-checkbox-indeterminate .ads-checkbox-icon::after {
277
+ width: calc(var(--_size) / 2);
278
+ height: calc(var(--_size) / 2);
279
+ border: 0;
280
+ background-color: var(--_bar);
281
+ transform: translate(-50%, -50%);
282
+ opacity: 1;
283
+ }
284
+
285
+ /* Hover anywhere over the label, box or text. */
286
+ .ads-checkbox:not(.ads-checkbox-disabled):hover .ads-checkbox-icon {
287
+ --_border: var(--ads-checkbox-border-hover);
288
+ }
289
+
290
+ .ads-checkbox-checked:not(.ads-checkbox-disabled, .ads-checkbox-indeterminate):hover
291
+ .ads-checkbox-icon {
292
+ --_border: var(--ads-checkbox-checked-bg-hover);
293
+ --_bg: var(--ads-checkbox-checked-bg-hover);
294
+ }
295
+
296
+ .ads-checkbox-input:focus-visible + .ads-checkbox-icon {
297
+ outline: var(--ads-focus-outline-width) solid var(--ads-color-focus-outline);
298
+ outline-offset: var(--ads-focus-outline-offset);
299
+ }
300
+
301
+ .ads-checkbox-label {
302
+ padding-inline: var(--ads-checkbox-label-padding);
303
+ }
304
+
305
+ /* Last, so the disabled colors win over the checked and indeterminate ones. */
306
+ .ads-checkbox-disabled {
307
+ color: var(--ads-color-text-disabled);
308
+ cursor: not-allowed;
309
+ }
310
+
311
+ .ads-checkbox-disabled .ads-checkbox-icon {
312
+ --_border: var(--ads-checkbox-disabled-border);
313
+ --_bg: var(--ads-checkbox-disabled-bg);
314
+ --_mark: var(--ads-checkbox-disabled-check-color);
315
+ --_bar: var(--ads-checkbox-disabled-check-color);
316
+ }
317
+
318
+ @media (prefers-reduced-motion: reduce) {
319
+ .ads-checkbox-icon,
320
+ .ads-checkbox-icon::after {
321
+ transition: none;
322
+ }
323
+ }
324
+ </style>
@@ -0,0 +1,41 @@
1
+ import { type Snippet } from 'svelte';
2
+ import type { HTMLInputAttributes } from 'svelte/elements';
3
+ import type { CheckboxClassNames, CheckboxStyles, CheckboxValue } from './types.js';
4
+ type CheckboxProps = Omit<HTMLInputAttributes, 'children' | 'class' | 'style' | 'type' | 'checked' | 'indeterminate' | 'value' | 'disabled' | 'name' | 'title' | 'onchange'> & {
5
+ /**
6
+ * Whether the checkbox is checked. Use `bind:checked` for two-way binding. Inside a
7
+ * `CheckboxGroup` the state comes from the group's `value` and this prop is ignored.
8
+ */
9
+ checked?: boolean;
10
+ /**
11
+ * The "partly checked" look of a "check all" control. It changes only the appearance and the
12
+ * state assistive technology reads (`mixed`); `checked` stays the value that is reported.
13
+ */
14
+ indeterminate?: boolean;
15
+ /** Whether the checkbox is disabled. A group's `disabled` applies as well. */
16
+ disabled?: boolean;
17
+ /** Identity inside a `CheckboxGroup` and the native `value` of the input. */
18
+ value?: CheckboxValue;
19
+ /** Native `name` of the input. Inside a group the group's `name` wins. */
20
+ name?: string;
21
+ /** Label content; it is the accessible name of the checkbox. */
22
+ children?: Snippet;
23
+ /** Called once per user toggle, after the state changed, with the new value and the native `change` event. */
24
+ onchange?: (checked: boolean, event: Event) => void;
25
+ /** Extra classes for the `root`, `icon` and `label` parts. */
26
+ classNames?: CheckboxClassNames;
27
+ /** Inline styles for the `root`, `icon` and `label` parts. */
28
+ styles?: CheckboxStyles;
29
+ /** Additional CSS class appended to the root classes. */
30
+ class?: string;
31
+ /** Inline style of the root; `styles.root` is applied after it. */
32
+ style?: string;
33
+ /** Native `title` of the root label, so the tooltip covers the box and the text. */
34
+ title?: string;
35
+ };
36
+ declare const Checkbox: import("svelte").Component<CheckboxProps, {
37
+ focus: (options?: FocusOptions) => void;
38
+ blur: () => void;
39
+ }, "checked">;
40
+ type Checkbox = ReturnType<typeof Checkbox>;
41
+ export default Checkbox;
@@ -0,0 +1,146 @@
1
+ <script lang="ts">
2
+ import type { Snippet } from 'svelte';
3
+ import type { HTMLAttributes } from 'svelte/elements';
4
+ import type {
5
+ CheckboxGroupClassNames,
6
+ CheckboxGroupStyles,
7
+ CheckboxOption,
8
+ CheckboxValue
9
+ } from './types.js';
10
+ import Checkbox from './Checkbox.svelte';
11
+ import { setCheckboxGroup } from './context.js';
12
+ import { classList, styleText } from '../internal/semantic.js';
13
+
14
+ type CheckboxGroupProps = Omit<
15
+ HTMLAttributes<HTMLDivElement>,
16
+ 'children' | 'class' | 'style' | 'role' | 'onchange'
17
+ > & {
18
+ /** The selected values. Use `bind:value` for two-way binding. */
19
+ value?: CheckboxValue[];
20
+ /** Renders one checkbox per entry. A string or a number is both the value and the label. */
21
+ options?: ReadonlyArray<CheckboxValue | CheckboxOption>;
22
+ /** Custom markup with `Checkbox` elements inside; ignored when `options` has entries. */
23
+ children?: Snippet;
24
+ /** Disables every checkbox of the group. */
25
+ disabled?: boolean;
26
+ /** Native `name` of every input of the group. */
27
+ name?: string;
28
+ /** Called once per user toggle with the new array and the `change` event of the toggled input. */
29
+ onchange?: (value: CheckboxValue[], event: Event) => void;
30
+ /** Extra classes for the `root`, `item`, `itemIcon` and `itemLabel` parts. */
31
+ classNames?: CheckboxGroupClassNames;
32
+ /** Inline styles for the `root`, `item`, `itemIcon` and `itemLabel` parts. */
33
+ styles?: CheckboxGroupStyles;
34
+ /** Additional CSS class appended to the root classes. */
35
+ class?: string;
36
+ /** Inline style of the root; `styles.root` is applied after it. */
37
+ style?: string;
38
+ };
39
+
40
+ let {
41
+ value = $bindable([]),
42
+ options = [],
43
+ children,
44
+ disabled = false,
45
+ name = undefined,
46
+ onchange,
47
+ classNames,
48
+ styles,
49
+ class: customClass,
50
+ style: customStyle,
51
+ ...rest
52
+ }: CheckboxGroupProps = $props();
53
+
54
+ const normalized = $derived<CheckboxOption[]>(
55
+ options.map((option) =>
56
+ typeof option === 'object' ? option : { label: String(option), value: option }
57
+ )
58
+ );
59
+ const hasOptions = $derived(normalized.length > 0);
60
+
61
+ // The checkboxes inside, in the order of mounting; with `options` their order is the options' order.
62
+ let registered: Array<() => CheckboxValue | undefined> = [];
63
+
64
+ /** The place of a value among the options or the mounted checkboxes; -1 for an unknown value. */
65
+ function orderOf(item: CheckboxValue): number {
66
+ if (hasOptions) return normalized.findIndex((option) => option.value === item);
67
+ return registered.findIndex((read) => read() === item);
68
+ }
69
+
70
+ /** Known values in their order, then the unknown ones in the order they had. */
71
+ function sorted(values: CheckboxValue[]): CheckboxValue[] {
72
+ const known = values.filter((item) => orderOf(item) >= 0).sort((a, b) => orderOf(a) - orderOf(b));
73
+ const unknown = values.filter((item) => orderOf(item) < 0);
74
+ return [...known, ...unknown];
75
+ }
76
+
77
+ function toggle(item: CheckboxValue, checked: boolean, event: Event): void {
78
+ const current = value;
79
+ const next = checked
80
+ ? current.includes(item)
81
+ ? current
82
+ : [...current, item]
83
+ : current.filter((other) => other !== item);
84
+ const ordered = sorted(next);
85
+ value = ordered;
86
+ onchange?.(ordered, event);
87
+ }
88
+
89
+ setCheckboxGroup({
90
+ isChecked: (item) => value.includes(item),
91
+ get disabled() {
92
+ return disabled;
93
+ },
94
+ get name() {
95
+ return name;
96
+ },
97
+ get classNames() {
98
+ return classNames;
99
+ },
100
+ get styles() {
101
+ return styles;
102
+ },
103
+ toggle,
104
+ register(read) {
105
+ registered = [...registered, read];
106
+ return () => {
107
+ registered = registered.filter((other) => other !== read);
108
+ };
109
+ }
110
+ });
111
+
112
+ const rootClass = $derived(classList('ads-checkbox-group', customClass, classNames?.root));
113
+ const rootStyle = $derived(styleText(customStyle, styles?.root));
114
+ </script>
115
+
116
+ <div {...rest} role="group" class={rootClass} style={rootStyle}>
117
+ {#if hasOptions}
118
+ {#each normalized as option (option.value)}
119
+ <Checkbox
120
+ value={option.value}
121
+ disabled={option.disabled}
122
+ title={option.title}
123
+ class={option.class}
124
+ style={option.style}
125
+ onchange={option.onchange}
126
+ >
127
+ {#if typeof option.label === 'string'}{option.label}{:else}{@render option.label()}{/if}
128
+ </Checkbox>
129
+ {/each}
130
+ {:else}
131
+ {@render children?.()}
132
+ {/if}
133
+ </div>
134
+
135
+ <style>
136
+ .ads-checkbox-group {
137
+ display: inline-flex;
138
+ flex-wrap: wrap;
139
+ column-gap: var(--ads-checkbox-group-gap);
140
+ box-sizing: border-box;
141
+ color: var(--ads-color-text);
142
+ font-family: var(--ads-font-family);
143
+ font-size: var(--ads-checkbox-font-size);
144
+ line-height: var(--ads-checkbox-line-height);
145
+ }
146
+ </style>
@@ -0,0 +1,28 @@
1
+ import type { Snippet } from 'svelte';
2
+ import type { HTMLAttributes } from 'svelte/elements';
3
+ import type { CheckboxGroupClassNames, CheckboxGroupStyles, CheckboxOption, CheckboxValue } from './types.js';
4
+ type CheckboxGroupProps = Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'class' | 'style' | 'role' | 'onchange'> & {
5
+ /** The selected values. Use `bind:value` for two-way binding. */
6
+ value?: CheckboxValue[];
7
+ /** Renders one checkbox per entry. A string or a number is both the value and the label. */
8
+ options?: ReadonlyArray<CheckboxValue | CheckboxOption>;
9
+ /** Custom markup with `Checkbox` elements inside; ignored when `options` has entries. */
10
+ children?: Snippet;
11
+ /** Disables every checkbox of the group. */
12
+ disabled?: boolean;
13
+ /** Native `name` of every input of the group. */
14
+ name?: string;
15
+ /** Called once per user toggle with the new array and the `change` event of the toggled input. */
16
+ onchange?: (value: CheckboxValue[], event: Event) => void;
17
+ /** Extra classes for the `root`, `item`, `itemIcon` and `itemLabel` parts. */
18
+ classNames?: CheckboxGroupClassNames;
19
+ /** Inline styles for the `root`, `item`, `itemIcon` and `itemLabel` parts. */
20
+ styles?: CheckboxGroupStyles;
21
+ /** Additional CSS class appended to the root classes. */
22
+ class?: string;
23
+ /** Inline style of the root; `styles.root` is applied after it. */
24
+ style?: string;
25
+ };
26
+ declare const CheckboxGroup: import("svelte").Component<CheckboxGroupProps, {}, "value">;
27
+ type CheckboxGroup = ReturnType<typeof CheckboxGroup>;
28
+ export default CheckboxGroup;
@@ -0,0 +1,173 @@
1
+ # Checkbox
2
+
3
+ A checkbox marks a value as chosen, with Ant Design-inspired styles and a Svelte 5 API. `Checkbox` renders a
4
+ native `<input type="checkbox">` inside a `<label>`; `CheckboxGroup` manages a list of them.
5
+
6
+ ## Usage
7
+
8
+ Import the design tokens once in the application entry point:
9
+
10
+ ```ts
11
+ import 'svelte-ant-design/tokens.css';
12
+ ```
13
+
14
+ ```svelte
15
+ <script lang="ts">
16
+ import { Checkbox } from 'svelte-ant-design';
17
+
18
+ let remember = $state(true);
19
+ </script>
20
+
21
+ <Checkbox bind:checked={remember}>Remember me</Checkbox>
22
+ ```
23
+
24
+ A group renders one checkbox per entry of `options` and holds the selected values:
25
+
26
+ ```svelte
27
+ <script lang="ts">
28
+ import { CheckboxGroup } from 'svelte-ant-design';
29
+
30
+ let fruits = $state(['Apple']);
31
+ </script>
32
+
33
+ <CheckboxGroup bind:value={fruits} options={['Apple', 'Pear', 'Orange']} aria-label="Fruits" />
34
+ ```
35
+
36
+ Objects add a `disabled` flag, a `title`, a `class`, a `style`, an `onchange` and a label that is text or a snippet:
37
+
38
+ ```svelte
39
+ {#snippet cherry()}<strong>Cherry</strong>{/snippet}
40
+
41
+ <CheckboxGroup
42
+ bind:value={fruits}
43
+ aria-label="Fruits"
44
+ options={[{ label: cherry, value: 'cherry' }, { label: 'Plum', value: 'plum', disabled: true }]}
45
+ />
46
+ ```
47
+
48
+ For your own layout put `Checkbox` elements in the group instead of `options`; each one needs a `value`:
49
+
50
+ ```svelte
51
+ <CheckboxGroup bind:value={days} aria-label="Days">
52
+ <div class="grid">
53
+ <Checkbox value="mon">Monday</Checkbox>
54
+ <Checkbox value="tue">Tuesday</Checkbox>
55
+ </div>
56
+ </CheckboxGroup>
57
+ ```
58
+
59
+ A "check all" control uses `indeterminate`, which changes only the look and the announced state:
60
+
61
+ ```svelte
62
+ <Checkbox
63
+ checked={all}
64
+ indeterminate={some}
65
+ onchange={(checked) => (selected = checked ? [...options] : [])}
66
+ >
67
+ Check all
68
+ </Checkbox>
69
+ ```
70
+
71
+ When the parent has to decide whether a change goes through (for example after a request), use a function
72
+ binding (Svelte 5.9 or newer); a refused change puts the box back:
73
+
74
+ ```svelte
75
+ <Checkbox
76
+ bind:checked={
77
+ () => enabled,
78
+ (next) => {
79
+ if (accepted) enabled = next;
80
+ }
81
+ }
82
+ >
83
+ Enable the feature
84
+ </Checkbox>
85
+ ```
86
+
87
+ ## Checkbox props
88
+
89
+ | Prop | Type | Default | Description |
90
+ |------|------|---------|-------------|
91
+ | `checked` | `boolean` (`$bindable`) | `false` | Whether the checkbox is checked. Use `bind:checked` for two-way binding; a plain value is the initial state. Inside a `CheckboxGroup` the state comes from the group's `value` and this prop is ignored. |
92
+ | `indeterminate` | `boolean` | `false` | The "partly checked" look of a "check all" control. It changes only the appearance and the announced state (`mixed`); `checked` stays the value that is reported and submitted. |
93
+ | `disabled` | `boolean` | `false` | Native `disabled` on the input. A group's `disabled` applies as well. |
94
+ | `value` | `string \| number` | — | The identity inside a `CheckboxGroup` and the native `value` of the input. Without it the input keeps the native `on`. |
95
+ | `name` | `string` | — | Native `name` of the input. Inside a group the group's `name` wins. |
96
+ | `children` | `Snippet` | — | The label. It is the accessible name. |
97
+ | `onchange` | `(checked: boolean, event: Event) => void` | — | Called once per user toggle, after the state changed, with the new value and the native `change` event (`event.target` is the input). Not called when the parent changes `checked`, nor while disabled. |
98
+ | `classNames` | `Partial<Record<'root' \| 'icon' \| 'label', string>>` | — | Extra classes for the parts of the checkbox. |
99
+ | `styles` | `Partial<Record<'root' \| 'icon' \| 'label', Record<string, string \| number>>>` | — | Inline styles for the parts. Names are kebab-case or custom properties; numbers are written as they are. |
100
+ | `class` | `string` | — | Additional CSS class appended to the root classes. |
101
+ | `style` | `string` | — | Inline style of the root; `styles.root` is written after it. |
102
+ | `title` | `string` | — | Native `title` of the root label, so the tooltip covers the box and the text. |
103
+ | Native attributes | `HTMLInputAttributes` | — | Forwarded to the `<input>` (`id`, `required`, `form`, `tabindex`, `aria-*`, `data-*`, `onfocus`, `onblur`, `onclick`, other handlers). `type`, `checked`, `indeterminate`, `value`, `disabled` and `onchange` belong to the component. |
104
+
105
+ The parts: `root` is the `<label>`, `icon` is the box (the check mark and the bar are drawn inside it), `label` holds the
106
+ text and exists only with `children`. Inline `styles` win over the component's styles. Classes from `classNames` and
107
+ `class` have the same specificity as the component's own rules, so use `styles` (or a more specific selector) when you
108
+ need to override a property the component already sets.
109
+
110
+ ## CheckboxGroup props
111
+
112
+ | Prop | Type | Default | Description |
113
+ |------|------|---------|-------------|
114
+ | `value` | `CheckboxValue[]` (`$bindable`) | `[]` | The selected values. Use `bind:value`; a plain value is the initial selection. The array follows the order of the options (or of the checkboxes in your markup); values that match nothing are kept after the known ones. |
115
+ | `options` | `ReadonlyArray<CheckboxValue \| CheckboxOption>` | `[]` | One checkbox per entry. A string or a number is both the value and the label. An object is `{ label, value, disabled?, title?, class?, style?, onchange? }` with `label` as text or a snippet. Values must be unique. When it has entries, `children` is ignored. |
116
+ | `children` | `Snippet` | — | Your own markup with `Checkbox` elements anywhere inside. Each one needs a `value`; outside production a missing one throws a `TypeError`. |
117
+ | `disabled` | `boolean` | `false` | Disables every checkbox of the group; the own `disabled` of an option disables that one alone. |
118
+ | `name` | `string` | — | Native `name` of every input of the group; it wins over the own `name` of a checkbox. |
119
+ | `onchange` | `(value: CheckboxValue[], event: Event) => void` | — | Called once per user toggle with a new array and the `change` event of the toggled input. The `onchange` of the checkbox or option runs first. Not called when the parent changes `value`. |
120
+ | `classNames` | `Partial<Record<'root' \| 'item' \| 'itemIcon' \| 'itemLabel', string>>` | — | `root` is the group; `item`, `itemIcon` and `itemLabel` are appended to the `root`, `icon` and `label` parts of every checkbox inside. |
121
+ | `styles` | `Partial<Record<'root' \| 'item' \| 'itemIcon' \| 'itemLabel', Record<string, string \| number>>>` | — | The same for inline styles; the own `styles` of a checkbox are written after the group's, so they win. |
122
+ | `class`, `style` | `string` | — | Root element (`styles.root` is written after `style`). |
123
+ | Native attributes | `HTMLAttributes<HTMLDivElement>` | — | Forwarded to the `<div>`. `role="group"` belongs to the component. |
124
+
125
+ The group has no methods; focus a checkbox inside it.
126
+
127
+ ## Methods
128
+
129
+ `Checkbox` has `focus(options?: FocusOptions)` and `blur()`, available through `bind:this`.
130
+
131
+ ## Forms
132
+
133
+ The input is native, so `name`, `value`, `required` and `form` work and only the checked boxes are submitted. A native
134
+ form reset does not change the state of the components (the state is `checked` or the group's `value`): the view is
135
+ put back to the state after the reset, so reset the state of the parent in the form's `onreset`.
136
+
137
+ ## Colors
138
+
139
+ In the light theme the default tokens are the values of the Ant Design token documentation: border `#d9d9d9`
140
+ (`#1677ff` on hover), checked fill `#1677ff` (`#4096ff` on hover), white check mark, disabled fill
141
+ `rgba(0, 0, 0, 0.04)`. They do **not** keep the contrast of the accessible set: the unchecked border is 1.41:1 against a
142
+ white page and the hover fill 2.99:1 (3:1 is needed for a part of a control). For a contrast guarantee import the
143
+ optional file after the tokens:
144
+
145
+ ```ts
146
+ import 'svelte-ant-design/tokens.css';
147
+ import 'svelte-ant-design/tokens-accessible.css';
148
+ ```
149
+
150
+ It darkens the unchecked border (`#737373`) and the checked hover fill (`#0958d9`). The dark theme needs no extra file.
151
+
152
+ ## Accessibility
153
+
154
+ - A native `<input type="checkbox">` in a `<label>`: Space toggles it, a click on the text works, the role and the checked state come from the browser, and an `indeterminate` checkbox is announced as mixed. Enter and the arrow keys do nothing.
155
+ - **A checkbox needs an accessible name:** its text (`children`), `aria-label`, `aria-labelledby` or an external `<label for>` that points at its `id` (forwarded to the input).
156
+ - A group has `role="group"`; name it with `aria-label` or `aria-labelledby`, or wrap it in a `<fieldset>` with a `<legend>`.
157
+ - A visible `:focus-visible` outline from the design tokens around the box, at least 3:1 against the page.
158
+ - The border, the check mark, the bar and the focus ring keep at least 3:1 contrast, and the label text 4.5:1, in every state: in the dark theme, and in the light theme when `tokens-accessible.css` is imported (see Colors).
159
+ - Under `prefers-reduced-motion: reduce` the transitions are disabled.
160
+ - Positions use logical properties, so the checkbox mirrors in right-to-left layouts. Toggling `checked`, `indeterminate` or `disabled` never changes the size of the control or moves its neighbours.
161
+
162
+ ## Scope decisions and differences from Ant Design
163
+
164
+ - `onchange` receives `(checked, event)` with the native `change` event; React passes an object with `target` and Vue the event. The group's `onchange` receives `(value, event)`; React and Vue pass only the array.
165
+ - `defaultChecked` and `defaultValue` (React) are not implemented: `bind:checked` and `bind:value` cover them. The function form of `classNames` / `styles` (React) is not implemented: compute the object in `$derived`. `nativeElement` (React) is not implemented.
166
+ - `value` is `string | number`; React and Vue also allow `boolean`, and React and Angular `any`. The Vue-only `indeterminate` of an option and the `label` slot are not implemented (a `label` snippet covers it).
167
+ - `Checkbox.Group` is a separate component, `CheckboxGroup`.
168
+ - See [`specs/checkbox.md`](../../../specs/checkbox.md) for the full comparison and the reasoning.
169
+
170
+ ## Live examples
171
+
172
+ Interactive examples of every option, with their code and the API tables, are on the
173
+ [documentation site](https://prostreyd.github.io/ant-design-svelte/components/checkbox/).
@@ -0,0 +1,20 @@
1
+ import type { CheckboxGroupClassNames, CheckboxGroupStyles, CheckboxValue } from './types.js';
2
+ /**
3
+ * What a CheckboxGroup shares with the checkboxes inside it. The properties are getters over the
4
+ * group's state, so a checkbox that reads them in a `$derived` follows their changes.
5
+ */
6
+ export interface CheckboxGroupContext {
7
+ /** Whether `value` is one of the selected values. */
8
+ isChecked(value: CheckboxValue): boolean;
9
+ readonly disabled: boolean;
10
+ readonly name: string | undefined;
11
+ readonly classNames: CheckboxGroupClassNames | undefined;
12
+ readonly styles: CheckboxGroupStyles | undefined;
13
+ /** Called by a checkbox after the user toggled it. */
14
+ toggle(value: CheckboxValue, checked: boolean, event: Event): void;
15
+ /** Registers a checkbox (its value is read when needed); returns the function that removes it. */
16
+ register(value: () => CheckboxValue | undefined): () => void;
17
+ }
18
+ export declare function setCheckboxGroup(context: CheckboxGroupContext): void;
19
+ /** The nearest CheckboxGroup, or `undefined` outside of one. */
20
+ export declare function getCheckboxGroup(): CheckboxGroupContext | undefined;
@@ -0,0 +1,9 @@
1
+ import { getContext, setContext } from 'svelte';
2
+ const KEY = Symbol('ads-checkbox-group');
3
+ export function setCheckboxGroup(context) {
4
+ setContext(KEY, context);
5
+ }
6
+ /** The nearest CheckboxGroup, or `undefined` outside of one. */
7
+ export function getCheckboxGroup() {
8
+ return getContext(KEY);
9
+ }
@@ -0,0 +1,32 @@
1
+ import type { Snippet } from 'svelte';
2
+ import type { SemanticStyle } from '../internal/semantic.js';
3
+ /** The identity of a checkbox inside a `CheckboxGroup` and the native `value` of its input. */
4
+ export type CheckboxValue = string | number;
5
+ /** The named parts of a Checkbox that `classNames` and `styles` address. */
6
+ export type CheckboxSemanticName = 'root' | 'icon' | 'label';
7
+ export type CheckboxClassNames = Partial<Record<CheckboxSemanticName, string>>;
8
+ export type CheckboxStyles = Partial<Record<CheckboxSemanticName, SemanticStyle>>;
9
+ /**
10
+ * The named parts of a CheckboxGroup: `root` is the group element; `item`, `itemIcon` and
11
+ * `itemLabel` reach the `root`, `icon` and `label` parts of every checkbox inside.
12
+ */
13
+ export type CheckboxGroupSemanticName = 'root' | 'item' | 'itemIcon' | 'itemLabel';
14
+ export type CheckboxGroupClassNames = Partial<Record<CheckboxGroupSemanticName, string>>;
15
+ export type CheckboxGroupStyles = Partial<Record<CheckboxGroupSemanticName, SemanticStyle>>;
16
+ /** One entry of the `options` of a CheckboxGroup. A plain string or number is both the value and the label. */
17
+ export interface CheckboxOption {
18
+ /** Label content: plain text, or a snippet for icons and markup. */
19
+ label: string | Snippet;
20
+ /** The value; it must be unique within the group. */
21
+ value: CheckboxValue;
22
+ /** Disables this option alone. */
23
+ disabled?: boolean;
24
+ /** Native `title` of the option's root label. */
25
+ title?: string;
26
+ /** Extra class of the option's root. */
27
+ class?: string;
28
+ /** Inline style of the option's root. */
29
+ style?: string;
30
+ /** Called when this option is toggled by the user, before the group's `onchange`. */
31
+ onchange?: (checked: boolean, event: Event) => void;
32
+ }
@@ -0,0 +1 @@
1
+ export {};
package/dist/index.d.ts CHANGED
@@ -1,5 +1,8 @@
1
- export declare const VERSION = "0.2.1";
1
+ export declare const VERSION = "0.3.0";
2
2
  export { default as Button } from './Button/Button.svelte';
3
3
  export { default as Switch } from './Switch/Switch.svelte';
4
+ export { default as Checkbox } from './Checkbox/Checkbox.svelte';
5
+ export { default as CheckboxGroup } from './Checkbox/CheckboxGroup.svelte';
6
+ export type { CheckboxClassNames, CheckboxGroupClassNames, CheckboxGroupSemanticName, CheckboxGroupStyles, CheckboxOption, CheckboxSemanticName, CheckboxStyles, CheckboxValue } from './Checkbox/types.js';
4
7
  export type { SwitchClassNames, SwitchSemanticName, SwitchSize, SwitchStyles } from './Switch/types.js';
5
8
  export type { ButtonHTMLType, ButtonIconPlacement, ButtonLoading, ButtonShape, ButtonSize, ButtonType } from './Button/types.js';
package/dist/index.js CHANGED
@@ -1,4 +1,6 @@
1
1
  // Public API of the library. Components are re-exported from here.
2
- export const VERSION = '0.2.1';
2
+ export const VERSION = '0.3.0';
3
3
  export { default as Button } from './Button/Button.svelte';
4
4
  export { default as Switch } from './Switch/Switch.svelte';
5
+ export { default as Checkbox } from './Checkbox/Checkbox.svelte';
6
+ export { default as CheckboxGroup } from './Checkbox/CheckboxGroup.svelte';
@@ -3,13 +3,14 @@
3
3
  *
4
4
  * tokens.css uses the values of the Ant Design token documentation, which do not reach WCAG AA for
5
5
  * text: white on the primary fill is 4.10:1 and on the danger fill 3.27:1 (4.5:1 is needed), and the
6
- * off track of a Switch is 1.84:1 against a white page (3:1 is needed). Import this file AFTER tokens.css
7
- * to get darker values for the `-solid`, `-text` and link tokens and for the Switch:
6
+ * off track of a Switch is 1.84:1 against a white page and the border of a Checkbox 1.41:1 (3:1 is needed).
7
+ * Import this file AFTER tokens.css to get darker values for the `-solid`, `-text` and link tokens, for the
8
+ * Switch and for the Checkbox border:
8
9
  *
9
10
  * import 'svelte-ant-design/tokens.css';
10
11
  * import 'svelte-ant-design/tokens-accessible.css';
11
12
  *
12
- * Every text pair is at least 4.5:1 and every track and handle at least 3:1, in every state. The dark
13
+ * Every text pair is at least 4.5:1 and every track, handle and checkbox border at least 3:1, in every state. The dark
13
14
  * theme needs no override and is not touched: the selector below does not apply when
14
15
  * `data-theme="dark"` is set. The selector is more specific than the `:root` of tokens.css, so the
15
16
  * order of the two imports does not matter.
@@ -39,4 +40,8 @@
39
40
  --ads-switch-track-on-hover: #0958d9;
40
41
  --ads-switch-track-on-active: #003eb3;
41
42
  --ads-switch-loading-opacity: 1;
43
+
44
+ --ads-checkbox-border: #737373;
45
+ /* #4096ff is 2.99:1 against a white page and 2.99:1 behind the white check mark: just under 3:1. */
46
+ --ads-checkbox-checked-bg-hover: #0958d9;
42
47
  }
package/dist/tokens.css CHANGED
@@ -84,9 +84,12 @@
84
84
 
85
85
  /* Motion */
86
86
  --ads-motion-duration: 0.2s;
87
+ --ads-motion-duration-fast: 0.1s;
88
+ --ads-motion-duration-slow: 0.3s;
87
89
  --ads-motion-duration-spinner: 1s;
88
90
  --ads-motion-duration-spinner-reduced: 2.5s;
89
91
  --ads-motion-ease: cubic-bezier(0.645, 0.045, 0.355, 1);
92
+ --ads-motion-ease-out-back: cubic-bezier(0.12, 0.4, 0.29, 1.46);
90
93
 
91
94
  /* Switch */
92
95
  --ads-switch-height: 22px;
@@ -123,6 +126,34 @@
123
126
  --ads-switch-handle-bg: #ffffff;
124
127
  --ads-switch-content-color: #ffffff;
125
128
  --ads-switch-loading-opacity: 0.65;
129
+
130
+ /* Checkbox: the dimensions of the global tokens the Ant Design documentation lists for it. */
131
+ --ads-checkbox-size: 16px;
132
+ --ads-checkbox-radius: 4px;
133
+ --ads-checkbox-border-width: 1px;
134
+ --ads-checkbox-check-width: 2px;
135
+ --ads-checkbox-font-size: 14px;
136
+ --ads-checkbox-line-height: 1.5714;
137
+ --ads-checkbox-label-padding: 8px;
138
+ --ads-checkbox-group-gap: 8px;
139
+
140
+ /*
141
+ * Checkbox colors. In the light theme the values are the ones of the Ant Design token documentation.
142
+ * The unchecked border is 1.41:1 against a white page (3:1 is needed for a part of a control), and the
143
+ * hover fill `#4096ff` is 2.99:1 against the page and behind the white check mark: `tokens-accessible.css`
144
+ * darkens both. The checked fill (`#1677ff`) and the check mark on it are 4.10:1 already.
145
+ * The dark theme below keeps 3:1 without it.
146
+ */
147
+ --ads-checkbox-bg: #ffffff;
148
+ --ads-checkbox-border: #d9d9d9;
149
+ --ads-checkbox-border-hover: #1677ff;
150
+ --ads-checkbox-checked-bg: #1677ff;
151
+ --ads-checkbox-checked-bg-hover: #4096ff;
152
+ --ads-checkbox-check-color: #ffffff;
153
+ --ads-checkbox-indeterminate-color: #1677ff;
154
+ --ads-checkbox-disabled-bg: rgba(0, 0, 0, 0.04);
155
+ --ads-checkbox-disabled-border: #d9d9d9;
156
+ --ads-checkbox-disabled-check-color: rgba(0, 0, 0, 0.25);
126
157
  }
127
158
 
128
159
  :root[data-theme='dark'] {
@@ -179,4 +210,16 @@
179
210
  --ads-switch-handle-bg: #ffffff;
180
211
  --ads-switch-content-color: #141414;
181
212
  --ads-switch-loading-opacity: 1;
213
+
214
+ /* The checkbox keeps 3:1 for the border on the page and for the mark on the fill, as the Switch does. */
215
+ --ads-checkbox-bg: #141414;
216
+ --ads-checkbox-border: #737373;
217
+ --ads-checkbox-border-hover: #4096ff;
218
+ --ads-checkbox-checked-bg: #3a8aff;
219
+ --ads-checkbox-checked-bg-hover: #3283f5;
220
+ --ads-checkbox-check-color: #141414;
221
+ --ads-checkbox-indeterminate-color: #3a8aff;
222
+ --ads-checkbox-disabled-bg: rgb(255 255 255 / 8%);
223
+ --ads-checkbox-disabled-border: #424242;
224
+ --ads-checkbox-disabled-check-color: rgb(255 255 255 / 30%);
182
225
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "svelte-ant-design",
3
- "version": "0.2.1",
3
+ "version": "0.3.0",
4
4
  "description": "An independent UI component library for Svelte 5, inspired by Ant Design.",
5
5
  "license": "MIT",
6
6
  "repository": {