@unframed/cli 0.2.0 → 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 +9 -0
- package/dist/cli.js +7 -1
- package/dist/cli.js.map +1 -1
- package/dist/commands/skill.js +34 -0
- package/dist/commands/skill.js.map +1 -0
- package/package.json +6 -4
- package/registry.json +101 -7
- package/skill/unframed/SKILL.md +57 -0
- package/skill/unframed/references/components.md +1830 -0
- package/skill/unframed/references/frameworks.md +383 -0
- package/skill/unframed/references/theming.md +41 -0
|
@@ -0,0 +1,383 @@
|
|
|
1
|
+
# Using Unframed 0.3.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"`.
|