@unframed/cli 0.2.0 → 0.4.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.
@@ -0,0 +1,383 @@
1
+ # Using Unframed 0.4.0 in each framework
2
+
3
+ ## HTML & JavaScript
4
+
5
+ Unframed components are standard custom elements: use them in plain HTML, or in any framework without its own package (Svelte, Solid, Astro, Lit…).
6
+
7
+ ### Install
8
+
9
+ ```bash
10
+ npm install @unframed/core @unframed/tokens
11
+ ```
12
+
13
+ ### Set up
14
+
15
+ Load the tokens once, then import the components you use. Each import registers its tags.
16
+
17
+ ```js
18
+ // main.js: load the tokens once, then the components you use
19
+ import '@unframed/tokens/tokens.css';
20
+ import '@unframed/core/button';
21
+ import '@unframed/core/input';
22
+ import '@unframed/core/checkbox';
23
+ import '@unframed/core/dialog';
24
+ // or every component at once: import '@unframed/core';
25
+ ```
26
+
27
+ ### Use the components
28
+
29
+ Form controls join the surrounding `<form>` like native ones: `required`, `FormData`, reset and validation messages work. Form controls fire native `input` and `change`; other components fire `uf-*` events (`uf-show`, `uf-hide`, `uf-tab-change`…). Methods like `dialog.show()` are on the elements.
30
+
31
+ ```html
32
+ <form id="signup">
33
+ <uf-input name="email" type="email" label="Email" required></uf-input>
34
+ <uf-checkbox name="terms" required>I accept the terms</uf-checkbox>
35
+ <uf-button type="submit">Sign up</uf-button>
36
+ </form>
37
+
38
+ <uf-dialog id="welcome" label="Welcome!">
39
+ <p>Check your inbox to confirm your email.</p>
40
+ <uf-button slot="footer" data-dialog="close">Got it</uf-button>
41
+ </uf-dialog>
42
+ ```
43
+
44
+ ```js
45
+ import { toast } from '@unframed/core';
46
+
47
+ const form = document.querySelector('#signup');
48
+ const dialog = document.querySelector('#welcome');
49
+
50
+ // Form controls take part in forms like native ones: validation, FormData, reset.
51
+ form.addEventListener('submit', (event) => {
52
+ event.preventDefault();
53
+ const data = new FormData(form); // { email: '…', terms: 'on' }
54
+ console.log(Object.fromEntries(data));
55
+ dialog.show();
56
+ });
57
+
58
+ // Events: native ones (input, change) and uf-* ones.
59
+ form.querySelector('uf-input').addEventListener('input', (event) => {
60
+ console.log(event.target.value);
61
+ });
62
+ dialog.addEventListener('uf-hide', () => toast('Welcome aboard!', { variant: 'success' }));
63
+ ```
64
+
65
+ ### Without a build step
66
+
67
+ ```html
68
+ <!doctype html>
69
+ <html lang="en">
70
+ <head>
71
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@unframed/tokens@0.2/dist/tokens.css" />
72
+ <script type="module" src="https://cdn.jsdelivr.net/npm/@unframed/core@0.2/+esm"></script>
73
+ </head>
74
+ <body>
75
+ <uf-button variant="primary">It works</uf-button>
76
+ </body>
77
+ </html>
78
+ ```
79
+
80
+ ### TypeScript
81
+
82
+ Importing a component adds its tag to `HTMLElementTagNameMap`:
83
+
84
+ ```ts
85
+ import type { UfDialog, UfInput } from '@unframed/core';
86
+
87
+ const dialog = document.querySelector('uf-dialog'); // typed as UfDialog | null
88
+ const input = document.querySelector<UfInput>('#email');
89
+ ```
90
+
91
+ ## React
92
+
93
+ `@unframed/react` has a React component for every element (`UfButton`, `UfDialog`…), with typed props and camelCase event handlers. React 18 and 19.
94
+
95
+ ### Install
96
+
97
+ ```bash
98
+ npm install @unframed/react @unframed/tokens
99
+ ```
100
+
101
+ ### Set up
102
+
103
+ ```tsx
104
+ // main.tsx: load the tokens once
105
+ import '@unframed/tokens/tokens.css';
106
+ ```
107
+
108
+ ### Use the components
109
+
110
+ Props are the element's properties. Events: `onInput` and `onChange` for form controls, `on` + the camelCase event name for the rest (`uf-hide` → `onUfHide`). Read values from `event.target` (the element). `toast()` and `registerIcons()` come from `@unframed/core`.
111
+
112
+ ```tsx
113
+ import { useState } from 'react';
114
+ import { toast, type UfCheckbox as UfCheckboxElement, type UfInput as UfInputElement } from '@unframed/core';
115
+ import { UfButton, UfCheckbox, UfDialog, UfInput } from '@unframed/react';
116
+
117
+ export function Signup() {
118
+ const [email, setEmail] = useState('');
119
+ const [terms, setTerms] = useState(false);
120
+ const [open, setOpen] = useState(false);
121
+
122
+ return (
123
+ <>
124
+ <form
125
+ onSubmit={(event) => {
126
+ event.preventDefault();
127
+ setOpen(true);
128
+ }}
129
+ >
130
+ <UfInput
131
+ name="email"
132
+ type="email"
133
+ label="Email"
134
+ required
135
+ value={email}
136
+ onInput={(event) => setEmail((event.target as UfInputElement).value)}
137
+ />
138
+ <UfCheckbox
139
+ name="terms"
140
+ required
141
+ checked={terms}
142
+ onChange={(event) => setTerms((event.target as UfCheckboxElement).checked)}
143
+ >
144
+ I accept the terms
145
+ </UfCheckbox>
146
+ <UfButton type="submit" disabled={!terms}>
147
+ Sign up
148
+ </UfButton>
149
+ </form>
150
+
151
+ <UfDialog
152
+ label="Welcome!"
153
+ open={open}
154
+ onUfHide={() => {
155
+ setOpen(false);
156
+ toast('Welcome aboard!', { variant: 'success' });
157
+ }}
158
+ >
159
+ <p>Check {email} to confirm your email.</p>
160
+ <UfButton slot="footer" data-dialog="close">
161
+ Got it
162
+ </UfButton>
163
+ </UfDialog>
164
+ </>
165
+ );
166
+ }
167
+ ```
168
+
169
+ ### Methods and refs
170
+
171
+ ```tsx
172
+ import { useRef } from 'react';
173
+ import type { UfDialog as UfDialogElement } from '@unframed/core';
174
+ import { UfButton, UfDialog } from '@unframed/react';
175
+
176
+ export function Help() {
177
+ const dialog = useRef<UfDialogElement>(null);
178
+ return (
179
+ <>
180
+ <UfButton onClick={() => dialog.current?.show()}>Help</UfButton>
181
+ <UfDialog ref={dialog} label="Help">…</UfDialog>
182
+ </>
183
+ );
184
+ }
185
+ ```
186
+
187
+ ## Vue
188
+
189
+ `@unframed/vue` has a Vue component for every element, with typed props and events, and `v-model` on every form control. No Vite configuration needed.
190
+
191
+ ### Install
192
+
193
+ ```bash
194
+ npm install @unframed/vue @unframed/tokens
195
+ ```
196
+
197
+ ### Set up
198
+
199
+ ```ts
200
+ // main.ts: load the tokens once
201
+ import { createApp } from 'vue';
202
+ import '@unframed/tokens/tokens.css';
203
+ import App from './App.vue';
204
+
205
+ createApp(App).mount('#app');
206
+ ```
207
+
208
+ ### Use the components
209
+
210
+ `v-model` binds `value` on inputs, textareas, selects, comboboxes and radio groups, `checked` on checkboxes and switches, and an array on checkbox groups (`v-model:indeterminate` for a checkbox's indeterminate state). Events keep their names: `@input`, `@change`, `@uf-hide`. Slots are the element's slots: `slot="footer"` on the child.
211
+
212
+ ```vue
213
+ <script setup lang="ts">
214
+ import { ref } from 'vue';
215
+ import { toast } from '@unframed/core';
216
+ import { UfButton, UfCheckbox, UfDialog, UfInput } from '@unframed/vue';
217
+
218
+ const email = ref('');
219
+ const terms = ref(false);
220
+ const open = ref(false);
221
+
222
+ function onHide() {
223
+ open.value = false;
224
+ toast('Welcome aboard!', { variant: 'success' });
225
+ }
226
+ </script>
227
+
228
+ <template>
229
+ <form @submit.prevent="open = true">
230
+ <UfInput v-model="email" name="email" type="email" label="Email" required />
231
+ <UfCheckbox v-model="terms" name="terms" required>I accept the terms</UfCheckbox>
232
+ <UfButton type="submit" :disabled="!terms">Sign up</UfButton>
233
+ </form>
234
+
235
+ <UfDialog label="Welcome!" :open="open" @uf-hide="onHide">
236
+ <p>Check {{ email }} to confirm your email.</p>
237
+ <UfButton slot="footer" data-dialog="close">Got it</UfButton>
238
+ </UfDialog>
239
+ </template>
240
+ ```
241
+
242
+ ### Register globally
243
+
244
+ ```ts
245
+ // main.ts: register every component globally instead of importing them
246
+ import { UnframedVue } from '@unframed/vue';
247
+
248
+ createApp(App).use(UnframedVue).mount('#app');
249
+ ```
250
+
251
+ ### Plain <uf-*> tags
252
+
253
+ ```ts
254
+ // vite.config.ts: only if you write <uf-*> tags instead of the components
255
+ import vue from '@vitejs/plugin-vue';
256
+ import { isUnframedElement } from '@unframed/vue';
257
+ import { defineConfig } from 'vite';
258
+
259
+ export default defineConfig({
260
+ plugins: [vue({ template: { compilerOptions: { isCustomElement: isUnframedElement } } })],
261
+ });
262
+ ```
263
+
264
+ ## Angular
265
+
266
+ `@unframed/angular` has standalone components with typed inputs and outputs, and form directives for `ngModel`, `formControl` and `formControlName`. Angular 20 or later. No `CUSTOM_ELEMENTS_SCHEMA` needed.
267
+
268
+ ### Install
269
+
270
+ ```bash
271
+ npm install @unframed/angular @unframed/tokens
272
+ ```
273
+
274
+ ### Set up
275
+
276
+ ```css
277
+ /* src/styles.css: load the tokens once */
278
+ @import '@unframed/tokens/tokens.css';
279
+ ```
280
+
281
+ ### Use the components
282
+
283
+ Outputs keep the event names: `(input)`, `(change)`, `(uf-hide)`. `UNFRAMED` imports every component and form directive (and bundles all of them); import single components by name, or from their entry point (`@unframed/angular/input`), to ship only what you use.
284
+
285
+ ```ts
286
+ import { Component, signal } from '@angular/core';
287
+ import { FormControl, FormGroup, ReactiveFormsModule, Validators } from '@angular/forms';
288
+ import { toast } from '@unframed/core';
289
+ import { UNFRAMED } from '@unframed/angular';
290
+
291
+ @Component({
292
+ selector: 'app-signup',
293
+ imports: [UNFRAMED, ReactiveFormsModule],
294
+ templateUrl: './signup.component.html',
295
+ })
296
+ export class SignupComponent {
297
+ readonly form = new FormGroup({
298
+ email: new FormControl('', { nonNullable: true, validators: [Validators.required, Validators.email] }),
299
+ terms: new FormControl(false, { nonNullable: true, validators: Validators.requiredTrue }),
300
+ });
301
+ readonly open = signal(false);
302
+
303
+ submit() {
304
+ if (this.form.valid) this.open.set(true);
305
+ }
306
+
307
+ welcome() {
308
+ this.open.set(false);
309
+ toast('Welcome aboard!', { variant: 'success' });
310
+ }
311
+ }
312
+ ```
313
+
314
+ ```html
315
+ <form [formGroup]="form" (ngSubmit)="submit()">
316
+ <uf-input formControlName="email" type="email" label="Email" required />
317
+ <uf-checkbox formControlName="terms" required>I accept the terms</uf-checkbox>
318
+ <uf-button type="submit" [disabled]="form.invalid">Sign up</uf-button>
319
+ </form>
320
+
321
+ <uf-dialog label="Welcome!" [open]="open()" (uf-hide)="welcome()">
322
+ <p>Check {{ form.value.email }} to confirm your email.</p>
323
+ <uf-button slot="footer" data-dialog="close">Got it</uf-button>
324
+ </uf-dialog>
325
+ ```
326
+
327
+ ### Bundle only what you use
328
+
329
+ ```ts
330
+ import { Component } from '@angular/core';
331
+ import { ReactiveFormsModule } from '@angular/forms';
332
+ // Each component has its own entry point, which also exports its form directive.
333
+ import { UfButton } from '@unframed/angular/button';
334
+ import { UfInput, UfTextValueAccessor } from '@unframed/angular/input';
335
+
336
+ // Importing by name from the root works too: unused components are left out.
337
+ import { UfDialog } from '@unframed/angular';
338
+
339
+ @Component({
340
+ selector: 'app-signup',
341
+ imports: [UfButton, UfInput, UfTextValueAccessor, UfDialog, ReactiveFormsModule],
342
+ templateUrl: './signup.component.html',
343
+ })
344
+ export class SignupComponent {}
345
+ ```
346
+
347
+ ### Template-driven forms
348
+
349
+ ```ts
350
+ import { Component } from '@angular/core';
351
+ import { FormsModule } from '@angular/forms';
352
+ import { UfCheckedValueAccessor, UfSwitch } from '@unframed/angular/switch';
353
+
354
+ @Component({
355
+ selector: 'app-settings',
356
+ imports: [UfSwitch, UfCheckedValueAccessor, FormsModule],
357
+ template: `<uf-switch [(ngModel)]="notifications">Notifications</uf-switch>`,
358
+ })
359
+ export class SettingsComponent {
360
+ notifications = true;
361
+ }
362
+ ```
363
+
364
+ ### Methods
365
+
366
+ Each component exposes its element as `el`:
367
+
368
+ ```ts
369
+ import { Component, viewChild } from '@angular/core';
370
+ import { UfButton, UfDialog } from '@unframed/angular';
371
+
372
+ @Component({
373
+ selector: 'app-help',
374
+ imports: [UfButton, UfDialog],
375
+ template: `
376
+ <uf-button (click)="dialog().el.show()">Help</uf-button>
377
+ <uf-dialog label="Help">…</uf-dialog>
378
+ `,
379
+ })
380
+ export class HelpComponent {
381
+ readonly dialog = viewChild.required(UfDialog);
382
+ }
383
+ ```
@@ -0,0 +1,41 @@
1
+ # Theming
2
+
3
+ Everything is driven by CSS custom properties, at three levels.
4
+
5
+ ## 1. Design tokens
6
+
7
+ Change a token and every component follows. Semantic tokens (`--uf-color-accent`, `--uf-color-danger`…) point at palettes (`--uf-palette-accent-50` … `-950`), so retheme by overriding either. Load overrides after `@unframed/tokens/tokens.css`.
8
+
9
+ ```css
10
+ :root {
11
+ --uf-palette-accent-600: #0f766e; /* the accent; generate the whole palette with the theme generator */
12
+ --uf-radius-control: 6px; /* rounded buttons and fields */
13
+ --uf-font-family-sans: 'Inter', sans-serif;
14
+ }
15
+ ```
16
+
17
+ The theme generator (https://p-db.github.io/unframed-ui/docs/theme-generator) builds a full palette from one color, with contrast checks, and outputs this CSS.
18
+
19
+ ## 2. Component properties
20
+
21
+ Each component documents its own custom properties, e.g. `--uf-button-radius`, `--uf-dialog-width`, `--uf-table-max-height`.
22
+
23
+ ```css
24
+ uf-button.pill { --uf-button-radius: 999px; }
25
+ uf-dialog.wide { --uf-dialog-width: 48rem; }
26
+ ```
27
+
28
+ ## 3. CSS parts
29
+
30
+ Shadow DOM keeps page CSS out by accident; `::part()` styles named internal elements on purpose. Any CSS property works on the part, plus states and pseudo-elements on it; you can't select inside a part.
31
+
32
+ ```css
33
+ uf-button::part(base) { text-transform: uppercase; }
34
+ uf-input:state(user-invalid)::part(box) { background: #fff5f5; }
35
+ ```
36
+
37
+ Use custom properties first; parts for anything they don't cover.
38
+
39
+ ## Dark mode
40
+
41
+ Dark mode follows the operating system. Force a theme on the page or any section with `data-uf-theme="light"` or `data-uf-theme="dark"`.