npm - @nqmcreative/ui - Versions diffs - 0.3.0 → 0.4.1 - Mend

@nqmcreative/ui 0.3.0 → 0.4.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.

Files changed (164) hide show

package/README.md +220 -28
package/cli/index.mjs +247 -70
package/dist/core/calendar.d.ts +1 -1
package/dist/core/calendar.js +1 -1
package/dist/core/color.d.ts +24 -0
package/dist/core/color.js +39 -0
package/dist/core/date.d.ts +3 -3
package/dist/core/date.js +1 -1
package/dist/core/files.d.ts +2 -3
package/dist/core/files.js +2 -3
package/dist/core/index.d.ts +9 -4
package/dist/core/index.js +6 -4
package/dist/core/number.d.ts +22 -0
package/dist/core/number.js +33 -0
package/dist/core/password.d.ts +1 -1
package/dist/core/password.js +1 -1
package/dist/core/pin.d.ts +23 -0
package/dist/core/pin.js +38 -0
package/dist/core/tags.d.ts +37 -0
package/dist/core/tags.js +51 -0
package/dist/core/time.d.ts +30 -0
package/dist/core/time.js +78 -0
package/dist/styles/matte/Alert.svelte +1 -3
package/dist/styles/matte/Breadcrumb.svelte +1 -4
package/dist/styles/matte/Calendar.svelte +6 -9
package/dist/styles/matte/ColorInput.svelte +107 -0
package/dist/styles/matte/ColorInput.svelte.d.ts +16 -0
package/dist/styles/matte/Combobox.svelte +3 -6
package/dist/styles/matte/CommandPalette.svelte +3 -6
package/dist/styles/matte/ConfirmDialog.svelte +2 -5
package/dist/styles/matte/ContextMenu.svelte +1 -4
package/dist/styles/matte/CurrencyInput.svelte +108 -0
package/dist/styles/matte/CurrencyInput.svelte.d.ts +26 -0
package/dist/styles/matte/DatePicker.svelte +9 -9
package/dist/styles/matte/DatePicker.svelte.d.ts +3 -0
package/dist/styles/matte/Drawer.svelte +1 -3
package/dist/styles/matte/Dropdown.svelte +2 -5
package/dist/styles/matte/Dropdown.svelte.d.ts +1 -1
package/dist/styles/matte/Dropzone.svelte +9 -12
package/dist/styles/matte/Dropzone.svelte.d.ts +1 -1
package/dist/styles/matte/FileInput.svelte +191 -0
package/dist/styles/matte/FileInput.svelte.d.ts +32 -0
package/dist/styles/matte/Footer.svelte +1 -1
package/dist/styles/matte/Footer.svelte.d.ts +1 -1
package/dist/styles/matte/InputAddon.svelte +36 -0
package/dist/styles/matte/InputAddon.svelte.d.ts +13 -0
package/dist/styles/matte/Modal.svelte +1 -3
package/dist/styles/matte/MultiSelect.svelte +5 -8
package/dist/styles/matte/Navbar.svelte +3 -9
package/dist/styles/matte/Pagination.svelte +3 -6
package/dist/styles/matte/PinInput.svelte +134 -0
package/dist/styles/matte/PinInput.svelte.d.ts +25 -0
package/dist/styles/matte/SearchInput.svelte +84 -0
package/dist/styles/matte/SearchInput.svelte.d.ts +24 -0
package/dist/styles/matte/Sidebar.svelte +3 -6
package/dist/styles/matte/Spinner.svelte +2 -5
package/dist/styles/matte/Spinner.svelte.d.ts +1 -1
package/dist/styles/matte/Table.svelte +5 -8
package/dist/styles/matte/TagsInput.svelte +170 -0
package/dist/styles/matte/TagsInput.svelte.d.ts +29 -0
package/dist/styles/matte/ThemeToggle.svelte +5 -8
package/dist/styles/matte/TimeInput.svelte +126 -0
package/dist/styles/matte/TimeInput.svelte.d.ts +21 -0
package/dist/styles/matte/Toaster.svelte +2 -5
package/dist/styles/matte/index.d.ts +10 -3
package/dist/styles/matte/index.js +9 -3
package/dist/styles/paper/Alert.svelte +1 -3
package/dist/styles/paper/Breadcrumb.svelte +1 -4
package/dist/styles/paper/Calendar.svelte +6 -9
package/dist/styles/paper/ColorInput.svelte +109 -0
package/dist/styles/paper/ColorInput.svelte.d.ts +16 -0
package/dist/styles/paper/Combobox.svelte +3 -6
package/dist/styles/paper/CommandPalette.svelte +3 -6
package/dist/styles/paper/ConfirmDialog.svelte +2 -5
package/dist/styles/paper/ContextMenu.svelte +1 -4
package/dist/styles/paper/CurrencyInput.svelte +108 -0
package/dist/styles/paper/CurrencyInput.svelte.d.ts +26 -0
package/dist/styles/paper/DatePicker.svelte +9 -9
package/dist/styles/paper/DatePicker.svelte.d.ts +3 -0
package/dist/styles/paper/Drawer.svelte +1 -3
package/dist/styles/paper/Dropdown.svelte +2 -5
package/dist/styles/paper/Dropdown.svelte.d.ts +1 -1
package/dist/styles/paper/Dropzone.svelte +9 -12
package/dist/styles/paper/Dropzone.svelte.d.ts +1 -1
package/dist/styles/paper/FileInput.svelte +201 -0
package/dist/styles/paper/FileInput.svelte.d.ts +32 -0
package/dist/styles/paper/Footer.svelte +1 -1
package/dist/styles/paper/Footer.svelte.d.ts +1 -1
package/dist/styles/paper/InputAddon.svelte +36 -0
package/dist/styles/paper/InputAddon.svelte.d.ts +13 -0
package/dist/styles/paper/Modal.svelte +1 -3
package/dist/styles/paper/MultiSelect.svelte +5 -8
package/dist/styles/paper/Navbar.svelte +3 -9
package/dist/styles/paper/Pagination.svelte +3 -6
package/dist/styles/paper/PinInput.svelte +134 -0
package/dist/styles/paper/PinInput.svelte.d.ts +25 -0
package/dist/styles/paper/SearchInput.svelte +89 -0
package/dist/styles/paper/SearchInput.svelte.d.ts +24 -0
package/dist/styles/paper/Sidebar.svelte +3 -6
package/dist/styles/paper/Spinner.svelte +2 -5
package/dist/styles/paper/Spinner.svelte.d.ts +1 -1
package/dist/styles/paper/Table.svelte +5 -8
package/dist/styles/paper/TagsInput.svelte +175 -0
package/dist/styles/paper/TagsInput.svelte.d.ts +29 -0
package/dist/styles/paper/ThemeToggle.svelte +5 -8
package/dist/styles/paper/TimeInput.svelte +152 -0
package/dist/styles/paper/TimeInput.svelte.d.ts +21 -0
package/dist/styles/paper/Toaster.svelte +3 -6
package/dist/styles/paper/index.d.ts +10 -3
package/dist/styles/paper/index.js +9 -3
package/dist/styles/sprout/Alert.svelte +1 -3
package/dist/styles/sprout/Breadcrumb.svelte +1 -4
package/dist/styles/sprout/Calendar.svelte +6 -9
package/dist/styles/sprout/ColorInput.svelte +109 -0
package/dist/styles/sprout/ColorInput.svelte.d.ts +16 -0
package/dist/styles/sprout/Combobox.svelte +3 -6
package/dist/styles/sprout/CommandPalette.svelte +3 -6
package/dist/styles/sprout/ConfirmDialog.svelte +2 -5
package/dist/styles/sprout/ContextMenu.svelte +1 -4
package/dist/styles/sprout/CurrencyInput.svelte +108 -0
package/dist/styles/sprout/CurrencyInput.svelte.d.ts +26 -0
package/dist/styles/sprout/DatePicker.svelte +9 -9
package/dist/styles/sprout/DatePicker.svelte.d.ts +3 -0
package/dist/styles/sprout/Drawer.svelte +1 -3
package/dist/styles/sprout/Dropdown.svelte +2 -5
package/dist/styles/sprout/Dropdown.svelte.d.ts +1 -1
package/dist/styles/sprout/Dropzone.svelte +9 -12
package/dist/styles/sprout/Dropzone.svelte.d.ts +1 -1
package/dist/styles/sprout/FileInput.svelte +202 -0
package/dist/styles/sprout/FileInput.svelte.d.ts +32 -0
package/dist/styles/sprout/Footer.svelte +1 -1
package/dist/styles/sprout/Footer.svelte.d.ts +1 -1
package/dist/styles/sprout/InputAddon.svelte +37 -0
package/dist/styles/sprout/InputAddon.svelte.d.ts +13 -0
package/dist/styles/sprout/Modal.svelte +1 -3
package/dist/styles/sprout/MultiSelect.svelte +5 -8
package/dist/styles/sprout/Navbar.svelte +3 -9
package/dist/styles/sprout/Pagination.svelte +3 -6
package/dist/styles/sprout/PinInput.svelte +135 -0
package/dist/styles/sprout/PinInput.svelte.d.ts +25 -0
package/dist/styles/sprout/SearchInput.svelte +89 -0
package/dist/styles/sprout/SearchInput.svelte.d.ts +24 -0
package/dist/styles/sprout/Sidebar.svelte +3 -6
package/dist/styles/sprout/Spinner.svelte +2 -5
package/dist/styles/sprout/Spinner.svelte.d.ts +1 -1
package/dist/styles/sprout/Table.svelte +5 -8
package/dist/styles/sprout/TagsInput.svelte +176 -0
package/dist/styles/sprout/TagsInput.svelte.d.ts +29 -0
package/dist/styles/sprout/ThemeToggle.svelte +5 -8
package/dist/styles/sprout/TimeInput.svelte +152 -0
package/dist/styles/sprout/TimeInput.svelte.d.ts +21 -0
package/dist/styles/sprout/Toaster.svelte +3 -6
package/dist/styles/sprout/index.d.ts +10 -3
package/dist/styles/sprout/index.js +9 -3
package/package.json +98 -19
package/registry.json +139 -38
package/dist/core/locale.svelte.d.ts +0 -93
package/dist/core/locale.svelte.js +0 -153
package/dist/styles/matte/LocaleProvider.svelte +0 -24
package/dist/styles/matte/LocaleProvider.svelte.d.ts +0 -10
package/dist/styles/paper/LocaleProvider.svelte +0 -24
package/dist/styles/paper/LocaleProvider.svelte.d.ts +0 -10
package/dist/styles/sprout/LocaleProvider.svelte +0 -24
package/dist/styles/sprout/LocaleProvider.svelte.d.ts +0 -10

package/README.md CHANGED Viewed

@@ -1,7 +1,7 @@
 # @nqmcreative/ui
 Svelte 5 (runes) + Tailwind CSS v4 component library. One package, **three
-styles**, 63 components each — the same props, the same behaviour, a different
+styles**, 70 components each — the same props, the same behaviour, a different
 look. Eight tones, light and dark, no runtime dependencies.
 | style    | import                   | character                                                                                                                      |
@@ -11,7 +11,7 @@ look. Eight tones, light and dark, no runtime dependencies.
 | `sprout` | `@nqmcreative/ui/sprout` | Warm and fully rounded — leaf green on cream, pill buttons, and a round display face. For school, community and family sites.  |
 The docs site lives in this repo — every component with a live demo, plus
-theming, locale and contributing guides. `bun run dev` to read it.
+theming and contributing guides. `bun run dev` to read it.
 ## Install
@@ -65,6 +65,131 @@ preconnect plus the no-flash theme script in `src/app.html`, above
 </details>
+## Without SvelteKit
+Nothing in the library imports `$app/*`, `$env/*` or `@sveltejs/kit`. The only
+peer dependency is `svelte` ^5, and every DOM call sits inside an action or an
+effect — so anything that compiles Svelte components runs these: a plain Vite
+app, or a Laravel app with Vite as its front end.
+The components ship as `.svelte` source, published under a `svelte` export
+condition. `@sveltejs/vite-plugin-svelte` is what resolves that condition and
+compiles them, so it is required outside SvelteKit. `nqm-ui init` detects which
+of the three project shapes it is in and wires the files that shape uses.
+### Svelte + Vite
+```bash
+npm create vite@latest myapp -- --template svelte-ts
+cd myapp
+npm i @nqmcreative/ui
+npm i -D tailwindcss @tailwindcss/vite
+npx nqm-ui init --style matte
+```
+`init` writes `src/app.css`, patches the `<head>` in `index.html`, and adds the
+CSS import to `src/main.ts`. The Vite config is the one thing it prints rather
+than rewrites:
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite';
+import { svelte } from '@sveltejs/vite-plugin-svelte';
+import tailwindcss from '@tailwindcss/vite';
+export default defineConfig({
+	plugins: [tailwindcss(), svelte()]
+});
+```
+### Laravel
+Vite is already how Laravel builds its front end, so Svelte and this package are
+the only additions.
+```bash
+npm i @nqmcreative/ui
+npm i -D svelte @sveltejs/vite-plugin-svelte tailwindcss @tailwindcss/vite
+npx nqm-ui init --style matte
+```
+```js
+// vite.config.js
+import { defineConfig } from 'vite';
+import laravel from 'laravel-vite-plugin';
+import { svelte } from '@sveltejs/vite-plugin-svelte';
+import tailwindcss from '@tailwindcss/vite';
+export default defineConfig({
+	plugins: [
+		laravel({ input: ['resources/css/app.css', 'resources/js/app.js'], refresh: true }),
+		tailwindcss(),
+		svelte()
+	]
+});
+```
+The entry CSS is `resources/css/app.css`, two levels below the project root, so
+`@source` walks two up. Laravel keeps its markup outside that folder, so point
+Tailwind at your own files too — otherwise the classes you write in Blade and in
+your Svelte islands go missing the same way the package's would:
+```css
+/* resources/css/app.css */
+@import 'tailwindcss';
+@import '@nqmcreative/ui/matte/theme.css';
+@import '@nqmcreative/ui/matte/fonts.css';
+@source '../../node_modules/@nqmcreative/ui/dist/styles/matte';
+@source '../js';
+@source '../views';
+```
+Nothing imports that CSS from JavaScript — Blade hands the path to Vite. The
+preconnect and the no-flash theme script go in the same `<head>`, which is what
+`init` patches:
+```blade
+{{-- resources/views/app.blade.php --}}
+<head>
+	@vite(['resources/css/app.css', 'resources/js/app.js'])
+	<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+	<script>
+		const saved = localStorage.getItem('nqm-theme');
+		if (saved === 'dark' || saved === 'light') document.documentElement.classList.add(saved);
+	</script>
+</head>
+```
+Then mount Svelte wherever the page needs it — one root component, or an island
+per view:
+```js
+// resources/js/app.js
+import { mount } from 'svelte';
+import App from './App.svelte';
+const target = document.getElementById('app');
+if (target) mount(App, { target });
+```
+```svelte
+<!-- resources/js/App.svelte -->
+<script>
+	import { Button, Field, Input } from '@nqmcreative/ui/matte';
+	let email = $state('');
+</script>
+<Field label="Work email">
+	<Input bind:value={email} placeholder="you@example.com" />
+</Field>
+<Button tone="accent">Get started</Button>
+```
+Blade renders the shell, Svelte renders the component — the two never fight over
+the same node, because the mount target is the only thing they share.
 ## Use
 The import names the style:
@@ -91,6 +216,75 @@ to nothing, on purpose: a style is a choice, and picking one by accident is the
 mistake this layout exists to prevent. Switching later is a find-and-replace of
 the word after `@nqmcreative/ui/`.
+### Form inputs
+`Input` takes any `type`, so an email or a URL field is a prop away, not a
+component:
+```svelte
+<Input type="email" inputmode="email" autocomplete="email" />
+```
+The eight below exist because each adds behaviour a `type` cannot — a second
+value, a keyboard rule, or a format that has to survive a round trip. All of
+them take `size`, `tone`, `invalid` and `disabled`, and mean the same by them as
+`Input` does.
+| component       | binds            | what it adds                                                       |
+| --------------- | ---------------- | ------------------------------------------------------------------ |
+| `SearchInput`   | `string`         | Clear button, plus `onsearch` debounced separately from the value. |
+| `InputAddon`    | —                | Fixed label welded to an `InputGroup`: `https://`, `.com`, `kg`.   |
+| `PinInput`      | `string`         | One box per character, paste spreading, arrow keys, `oncomplete`.  |
+| `TagsInput`     | `string[]`       | Free-text tokens on Enter, deduplicated, capped, split on paste.   |
+| `CurrencyInput` | `number \| null` | Grouping applied on blur, so the bound value stays a number.       |
+| `TimeInput`     | `string`         | Steppers and bounds over an `HH:MM` string.                        |
+| `ColorInput`    | `string`         | Native swatch and hex field kept in step, normalised to `#rrggbb`. |
+| `FileInput`     | `File[]`         | One-line picker with `Dropzone`'s type, size and count validation. |
+Four of them wrap `Input` and fill its prefix or suffix slot — `SearchInput`,
+`CurrencyInput`, `TimeInput`, `ColorInput` — so a change to the field's border
+or focus ring reaches them for free. The other four draw their own box.
+```svelte
+<script lang="ts">
+	import { CurrencyInput, PinInput, TagsInput, TimeInput } from '@nqmcreative/ui/matte';
+	let price = $state<number | null>(1250000); // a number, not a formatted string
+	let code = $state(''); // shorter than `length` means incomplete
+	let tags = $state(['svelte']);
+	let start = $state('09:00'); // what <input type="time"> would post
+</script>
+<CurrencyInput bind:value={price} currency="Rp" group="." decimal="," precision={0} />
+<PinInput bind:value={code} length={6} groupAfter={3} oncomplete={verify} />
+<TagsInput bind:tags max={6} onreject={(reason) => toast.error(reason)} />
+<TimeInput bind:value={start} min="08:00" max="17:00" step={15} />
+```
+Two details worth knowing before you wire them up. `CurrencyInput` groups on
+blur and not under the caret, because formatting as you type is what pushes the
+caret around mid-word. And `TagsInput` reports every refusal — duplicate, too
+short, list full — through `onreject`, because a field that silently ignores
+Enter reads as broken.
+The rules are all in `@nqmcreative/ui/core`, not in any style:
+```ts
+import {
+	addTag,
+	splitTags, // tokens
+	fillFrom,
+	sanitisePin, // codes
+	parseTime,
+	clampTime, // clock
+	formatGrouped,
+	parseGrouped, // money
+	normaliseHex, // colour
+	sortFiles,
+	formatSize // files
+} from '@nqmcreative/ui/core';
+```
 ### Tones
 Eight of them — `brand`, `accent`, `violet`, `info`, `success`, `warning`,
@@ -113,33 +307,31 @@ Each style's `theme.css` ships both palettes; nothing in a component says
 `dark:`. `<html class="dark">` or `class="light"` forces one, bare `<html>`
 follows the OS. `ThemeToggle` handles all three.
-### Locale
+### Built-in strings
-Every built-in string — ARIA names, `No data`, the calendar's month names —
-comes from one object, shared by every style:
-```js
-import { setLocale, idID } from '@nqmcreative/ui/core';
-setLocale(idID);
-```
+Components render English text of their own — ARIA names, `No data`, `Choose
+file` — written inline at the call site. Where a caller would plausibly want to
+change one, it is a prop: `<Table empty="…">`, `<Dropzone label="…">`,
+`<FileInput placeholder="…">`.
-`enUS` and `idID` ship with the package; pass a partial to change a few keys.
-Under SSR use `<LocaleProvider>` instead, so the locale is scoped to a request.
+Dates are the one place the browser decides: `Calendar` and `DatePicker` take
+month and weekday names from `Intl` with no locale argument, so they follow the
+reader's own system. The order of the parts the field parses and prints is
+explicit instead — `<DatePicker format="dmy">`, defaulting to `dmy`.
 ## Layout
 ```
 src/lib/core/            behaviour, a11y, types — no markup, no classes
-src/lib/styles/matte/    63 components
-src/lib/styles/paper/    63 components
-src/lib/styles/sprout/   63 components
+src/lib/styles/matte/    70 components
+src/lib/styles/paper/    70 components
+src/lib/styles/sprout/   70 components
 scripts/catalogue.mjs    the list every style must implement
 ```
 `core` holds what has no opinion about looks: focus traps, roving keyboard
 navigation, viewport-aware anchoring, date maths, file validation, table
-sorting, the toast queue, the locale strings. There is no `matte` version of a
+sorting, the toast queue. There is no `matte` version of a
 focus trap, so no style writes one.
 A style holds only markup and classes. It may differ from another completely —
@@ -150,17 +342,17 @@ same.
 ## Components
-| group        | components                                                                                                                                                                                                                 |
-| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Actions      | `Button`, `Link`                                                                                                                                                                                                           |
-| Forms        | `Input`, `Textarea`, `Select`, `Combobox`, `MultiSelect`, `DatePicker`, `Calendar`, `Checkbox`, `CheckboxGroup`, `Radio`, `RadioGroup`, `SegmentedControl`, `Switch`, `Slider`, `InputGroup`, `Dropzone`, `Field`, `Label` |
-| Data display | `Badge`, `Avatar`, `AvatarGroup`, `Card`, `Stat`, `Table`, `Kbd`                                                                                                                                                           |
-| Feedback     | `Alert`, `Toaster` + `toast`, `Progress`, `Spinner`, `Skeleton`, `EmptyState`                                                                                                                                              |
-| Layout & nav | `Divider`, `Tabs`, `Accordion`, `AccordionItem`, `Breadcrumb`, `Pagination`, `Steps`                                                                                                                                       |
-| App shell    | `Navbar`, `Sidebar`, `Footer`                                                                                                                                                                                              |
-| Overlay      | `Modal`, `ConfirmDialog`, `Drawer`, `Dropdown` + `MenuItem` + `MenuSeparator`, `ContextMenu`, `CommandPalette`, `Popover`, `Tooltip`                                                                                       |
-| Marketing    | `HeroSection`, `FeatureGrid`, `FeatureCard`, `PricingCard`, `Testimonial`, `LogoCloud`, `CTASection`, `StatsBand`                                                                                                          |
-| System       | `ThemeToggle`, `LocaleProvider`                                                                                                                                                                                            |
+| group        | components                                                                                                                                                                                                                                                                                                                                |
+| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Actions      | `Button`, `Link`                                                                                                                                                                                                                                                                                                                          |
+| Forms        | `Input`, `Textarea`, `Select`, `Combobox`, `MultiSelect`, `DatePicker`, `Calendar`, `Checkbox`, `CheckboxGroup`, `Radio`, `RadioGroup`, `SegmentedControl`, `Switch`, `Slider`, `InputGroup`, `InputAddon`, `SearchInput`, `PinInput`, `TagsInput`, `CurrencyInput`, `TimeInput`, `ColorInput`, `FileInput`, `Dropzone`, `Field`, `Label` |
+| Data display | `Badge`, `Avatar`, `AvatarGroup`, `Card`, `Stat`, `Table`, `Kbd`                                                                                                                                                                                                                                                                          |
+| Feedback     | `Alert`, `Toaster` + `toast`, `Progress`, `Spinner`, `Skeleton`, `EmptyState`                                                                                                                                                                                                                                                             |
+| Layout & nav | `Divider`, `Tabs`, `Accordion`, `AccordionItem`, `Breadcrumb`, `Pagination`, `Steps`                                                                                                                                                                                                                                                      |
+| App shell    | `Navbar`, `Sidebar`, `Footer`                                                                                                                                                                                                                                                                                                             |
+| Overlay      | `Modal`, `ConfirmDialog`, `Drawer`, `Dropdown` + `MenuItem` + `MenuSeparator`, `ContextMenu`, `CommandPalette`, `Popover`, `Tooltip`                                                                                                                                                                                                      |
+| Marketing    | `HeroSection`, `FeatureGrid`, `FeatureCard`, `PricingCard`, `Testimonial`, `LogoCloud`, `CTASection`, `StatsBand`                                                                                                                                                                                                                         |
+| System       | `ThemeToggle`                                                                                                                                                                                                                                                                                                                             |
 Overlays are built on the native top layer and three in-house actions
 (`portal`, `focusTrap`, `anchored`) rather than a positioning dependency.