@nqmcreative/ui 0.2.3 → 0.4.0

package/dist/core/locale.svelte.d.ts

@@ -52,6 +52,14 @@ export interface Locale {
     passwordStrength: [string, string, string, string, string];
     decrease: string;
     increase: string;
+    chooseFile: string;
+    noFile: string;
+    clearSearch: string;
+    /** Prefixed to the box number, so box three is labelled `Digit 3`. */
+    digit: string;
+    addTag: string;
+    duplicateTag: string;
+    pickColour: string;
     /** BCP 47 tag handed to `Intl` for month and weekday names. */
     dateLocale: string;
     /** Order of the date parts the input accepts and prints. */

package/dist/core/locale.svelte.js

@@ -51,6 +51,13 @@ export const enUS = {
     passwordStrength: ['Too short', 'Weak', 'Fair', 'Good', 'Strong'],
     decrease: 'Decrease',
     increase: 'Increase',
+    chooseFile: 'Choose file',
+    noFile: 'No file chosen',
+    clearSearch: 'Clear search',
+    digit: 'Digit',
+    addTag: 'Add a tag',
+    duplicateTag: 'Already added',
+    pickColour: 'Pick a colour',
     dateLocale: 'en-US',
     dateFormat: 'mdy',
     today: 'Today',
@@ -103,6 +110,13 @@ export const idID = {
     passwordStrength: ['Terlalu pendek', 'Lemah', 'Cukup', 'Baik', 'Kuat'],
     decrease: 'Kurangi',
     increase: 'Tambah',
+    chooseFile: 'Pilih berkas',
+    noFile: 'Belum ada berkas',
+    clearSearch: 'Hapus pencarian',
+    digit: 'Digit',
+    addTag: 'Tambah tag',
+    duplicateTag: 'Sudah ditambahkan',
+    pickColour: 'Pilih warna',
     dateLocale: 'id-ID',
     dateFormat: 'dmy',
     today: 'Hari ini',

package/dist/core/number.d.ts

@@ -5,3 +5,25 @@ export declare function stepDecimals(step: number): number;
 export declare function clampToStep(value: number, min: number, max: number, step: number): number;
 /** Position of `value` within `min…max`, as 0–100. */
 export declare function percentOf(value: number, min: number, max: number): number;
+/**
+ * How a grouped number is written. Separators are the app's to choose rather
+ * than `Intl`'s, because the field has to *parse* what it prints — and a
+ * locale that groups with a non-breaking space produces a character nobody can
+ * type back in.
+ */
+export interface GroupOptions {
+    /** Thousands separator. */
+    group?: string;
+    /** Decimal separator. */
+    decimal?: string;
+    /** Fixed decimal places. `undefined` keeps whatever was typed. */
+    precision?: number;
+}
+/** `1234567.5` → `1,234,567.50`, or `1.234.567,50` in a locale that swaps them. */
+export declare function formatGrouped(value: number, options?: GroupOptions): string;
+/**
+ * The inverse, and deliberately forgiving: anything that is not a digit, a
+ * minus or the decimal separator is dropped, so a pasted `Rp 1.250.000,-`
+ * still reads as a number. `null` means there were no digits at all.
+ */
+export declare function parseGrouped(text: string, options?: GroupOptions): number | null;

package/dist/core/number.js

@@ -15,3 +15,36 @@ export function percentOf(value, min, max) {
         return 0;
     return Math.min(100, Math.max(0, ((value - min) / (max - min)) * 100));
 }
+/** `1234567.5` → `1,234,567.50`, or `1.234.567,50` in a locale that swaps them. */
+export function formatGrouped(value, options = {}) {
+    const { group = ',', decimal = '.', precision } = options;
+    if (!Number.isFinite(value))
+        return '';
+    const fixed = precision === undefined ? String(value) : value.toFixed(precision);
+    const negative = fixed.startsWith('-');
+    const [whole, fraction] = (negative ? fixed.slice(1) : fixed).split('.');
+    // Replaced through a function so a separator that looks like `$&` stays put.
+    const grouped = whole.replace(/\B(?=(\d{3})+(?!\d))/g, () => group);
+    return `${negative ? '-' : ''}${grouped}${fraction ? decimal + fraction : ''}`;
+}
+/**
+ * The inverse, and deliberately forgiving: anything that is not a digit, a
+ * minus or the decimal separator is dropped, so a pasted `Rp 1.250.000,-`
+ * still reads as a number. `null` means there were no digits at all.
+ */
+export function parseGrouped(text, options = {}) {
+    const { decimal = '.' } = options;
+    let cleaned = '';
+    for (const char of text) {
+        if (char === decimal)
+            cleaned += '.';
+        else if (char >= '0' && char <= '9')
+            cleaned += char;
+        else if (char === '-' && cleaned === '')
+            cleaned += char;
+    }
+    if (!cleaned || cleaned === '-' || cleaned === '.')
+        return null;
+    const value = Number(cleaned);
+    return Number.isFinite(value) ? value : null;
+}

package/dist/core/pin.d.ts

@@ -0,0 +1,23 @@
+/**
+ * One-time codes: what a character box accepts, and where a paste lands.
+ *
+ * The value is a plain compact string — `'0421'` means the first four boxes
+ * are filled and the rest are empty. Holes are impossible by construction,
+ * which is what lets the component always know which box to focus next.
+ */
+export type PinMode = 'numeric' | 'alphanumeric';
+/** Strips whatever the mode refuses, then trims to `length` characters. */
+export declare function sanitisePin(text: string, mode?: PinMode, length?: number): string;
+/**
+ * Writes `text` into the boxes from `index` on.
+ *
+ * One keystroke replaces one box and leaves the tail alone; a six-character
+ * paste into the first box fills all six. Anything past `length` is dropped
+ * rather than wrapped, because the extra characters were never part of a code
+ * this long.
+ */
+export declare function fillFrom(value: string, index: number, text: string, length: number, mode?: PinMode): string;
+/** Clears one box and everything after it — what Backspace on a filled box does. */
+export declare function clearFrom(value: string, index: number): string;
+/** The box the caret belongs in: the first empty one, or the last. */
+export declare function caretIndex(value: string, length: number): number;

package/dist/core/pin.js

@@ -0,0 +1,38 @@
+/**
+ * One-time codes: what a character box accepts, and where a paste lands.
+ *
+ * The value is a plain compact string — `'0421'` means the first four boxes
+ * are filled and the rest are empty. Holes are impossible by construction,
+ * which is what lets the component always know which box to focus next.
+ */
+const ALLOWED = {
+    numeric: /[^0-9]/g,
+    alphanumeric: /[^0-9a-zA-Z]/g
+};
+/** Strips whatever the mode refuses, then trims to `length` characters. */
+export function sanitisePin(text, mode = 'numeric', length = Infinity) {
+    return text.replace(ALLOWED[mode], '').slice(0, length);
+}
+/**
+ * Writes `text` into the boxes from `index` on.
+ *
+ * One keystroke replaces one box and leaves the tail alone; a six-character
+ * paste into the first box fills all six. Anything past `length` is dropped
+ * rather than wrapped, because the extra characters were never part of a code
+ * this long.
+ */
+export function fillFrom(value, index, text, length, mode = 'numeric') {
+    const head = value.slice(0, index);
+    const clean = sanitisePin(text, mode, length - head.length);
+    if (!clean)
+        return value;
+    return (head + clean + value.slice(index + clean.length)).slice(0, length);
+}
+/** Clears one box and everything after it — what Backspace on a filled box does. */
+export function clearFrom(value, index) {
+    return value.slice(0, index);
+}
+/** The box the caret belongs in: the first empty one, or the last. */
+export function caretIndex(value, length) {
+    return Math.min(value.length, length - 1);
+}

package/dist/core/tags.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Free-text tokens: what counts as a new tag, and why one was turned away.
+ *
+ * The rejection is returned rather than thrown or swallowed, so the component
+ * can say *why* nothing happened — a silent no-op on a duplicate reads like a
+ * broken field.
+ */
+export type TagRejection = 'empty' | 'short' | 'duplicate' | 'full';
+export interface TagRules {
+    /** Trim the ends and collapse inner runs of whitespace. Default `true`. */
+    trim?: boolean;
+    /** Ignore case when refusing duplicates. Default `true`. */
+    caseInsensitive?: boolean;
+    /** Cap on how many tags may be held. `0` means no limit. */
+    max?: number;
+    /** Shortest a tag may be, after trimming. */
+    minLength?: number;
+}
+/**
+ * Sorts one commit into the next list, or the reason there isn't one.
+ *
+ * Order matters, the way it does in `sortFiles`: a tag is judged on being
+ * present, then long enough, then unique, then whether there is room — so the
+ * message a user sees is the first rule they actually broke.
+ */
+export declare function addTag(tags: string[], raw: string, rules?: TagRules): {
+    tags: string[];
+    rejected?: TagRejection;
+};
+/**
+ * Splits pasted text so one paste can commit several tags.
+ *
+ * Scanned character by character rather than with a RegExp: the separators are
+ * the app's to choose, and building a character class out of them means
+ * escaping every one that happens to be a metacharacter.
+ */
+export declare function splitTags(text: string, separators?: readonly string[]): string[];

package/dist/core/tags.js

@@ -0,0 +1,51 @@
+/**
+ * Free-text tokens: what counts as a new tag, and why one was turned away.
+ *
+ * The rejection is returned rather than thrown or swallowed, so the component
+ * can say *why* nothing happened — a silent no-op on a duplicate reads like a
+ * broken field.
+ */
+/**
+ * Sorts one commit into the next list, or the reason there isn't one.
+ *
+ * Order matters, the way it does in `sortFiles`: a tag is judged on being
+ * present, then long enough, then unique, then whether there is room — so the
+ * message a user sees is the first rule they actually broke.
+ */
+export function addTag(tags, raw, rules = {}) {
+    const { trim = true, caseInsensitive = true, max = 0, minLength = 1 } = rules;
+    const value = trim ? raw.trim().replace(/\s+/g, ' ') : raw;
+    if (!value)
+        return { tags, rejected: 'empty' };
+    if (value.length < minLength)
+        return { tags, rejected: 'short' };
+    const fold = (text) => (caseInsensitive ? text.toLowerCase() : text);
+    if (tags.some((tag) => fold(tag) === fold(value)))
+        return { tags, rejected: 'duplicate' };
+    if (max && tags.length >= max)
+        return { tags, rejected: 'full' };
+    return { tags: [...tags, value] };
+}
+/**
+ * Splits pasted text so one paste can commit several tags.
+ *
+ * Scanned character by character rather than with a RegExp: the separators are
+ * the app's to choose, and building a character class out of them means
+ * escaping every one that happens to be a metacharacter.
+ */
+export function splitTags(text, separators = [',']) {
+    const marks = new Set([...separators, '\n', '\r', '\t']);
+    const found = [];
+    let current = '';
+    for (const char of text) {
+        if (marks.has(char)) {
+            found.push(current);
+            current = '';
+        }
+        else {
+            current += char;
+        }
+    }
+    found.push(current);
+    return found.map((tag) => tag.trim()).filter(Boolean);
+}

package/dist/core/time.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Clock times as `HH:MM` strings — the shape `<input type="time">` uses, so a
+ * form posts exactly what the browser would have posted.
+ *
+ * Everything here works in minutes since midnight. A day is 1440 of them, and
+ * nothing in this module crosses that boundary: stepping past 23:59 stops
+ * there rather than wrapping into a day this module cannot name.
+ */
+export declare const MINUTES_IN_DAY = 1440;
+/**
+ * Reads `9:5`, `09:05`, `0905` or `09:05:30` into minutes since midnight.
+ * Returns `null` for anything that is not a time, including 24:00 and 12:60.
+ */
+export declare function parseTime(text: string): number | null;
+/** Minutes since midnight back to `HH:MM`, always four digits and a colon. */
+export declare function formatTime(minutes: number): string;
+/** Clamps into `min…max` and snaps to the nearest multiple of `step` minutes. */
+export declare function clampTime(minutes: number, min?: string, max?: string, step?: number): number;
+/**
+ * Moves by whole steps. Stops at the bounds instead of wrapping — a stepper
+ * that rolls 23:55 round to 00:00 turns a late meeting into an early one.
+ */
+export declare function stepTime(value: string, direction: 1 | -1, step?: number, min?: string, max?: string): string;
+/**
+ * `13:05` as the locale writes it — `1:05 PM` in en-US, `13.05` in id-ID.
+ *
+ * Display only. The bound value stays `HH:MM` whatever this returns, because a
+ * localised string is not something a form can post.
+ */
+export declare function formatClock(value: string, locale: string, hour12?: boolean): string;

package/dist/core/time.js

@@ -0,0 +1,78 @@
+/**
+ * Clock times as `HH:MM` strings — the shape `<input type="time">` uses, so a
+ * form posts exactly what the browser would have posted.
+ *
+ * Everything here works in minutes since midnight. A day is 1440 of them, and
+ * nothing in this module crosses that boundary: stepping past 23:59 stops
+ * there rather than wrapping into a day this module cannot name.
+ */
+export const MINUTES_IN_DAY = 1440;
+/**
+ * Reads `9:5`, `09:05`, `0905` or `09:05:30` into minutes since midnight.
+ * Returns `null` for anything that is not a time, including 24:00 and 12:60.
+ */
+export function parseTime(text) {
+    const trimmed = text.trim();
+    // Digits and colons only: `9a` and `later` are refusals, not a hint that
+    // someone meant 09:00. Without this a bare `Number('')` reads as midnight.
+    if (!trimmed || !/^[0-9:]+$/.test(trimmed))
+        return null;
+    const digits = trimmed.replace(/[^0-9]/g, '');
+    if (!digits)
+        return null;
+    let hours;
+    let minutes;
+    if (trimmed.includes(':')) {
+        const [rawHours, rawMinutes = '0'] = trimmed.split(':');
+        hours = Number(rawHours);
+        minutes = Number(rawMinutes);
+    }
+    else if (digits.length <= 2) {
+        // A bare number is an hour: `9` means 09:00.
+        hours = Number(digits);
+        minutes = 0;
+    }
+    else {
+        hours = Number(digits.slice(0, digits.length - 2));
+        minutes = Number(digits.slice(-2));
+    }
+    if (!Number.isInteger(hours) || !Number.isInteger(minutes))
+        return null;
+    if (hours < 0 || hours > 23 || minutes < 0 || minutes > 59)
+        return null;
+    return hours * 60 + minutes;
+}
+/** Minutes since midnight back to `HH:MM`, always four digits and a colon. */
+export function formatTime(minutes) {
+    const total = Math.max(0, Math.min(MINUTES_IN_DAY - 1, Math.round(minutes)));
+    const hours = Math.floor(total / 60);
+    return `${String(hours).padStart(2, '0')}:${String(total % 60).padStart(2, '0')}`;
+}
+/** Clamps into `min…max` and snaps to the nearest multiple of `step` minutes. */
+export function clampTime(minutes, min, max, step = 1) {
+    const floor = min ? (parseTime(min) ?? 0) : 0;
+    const ceiling = max ? (parseTime(max) ?? MINUTES_IN_DAY - 1) : MINUTES_IN_DAY - 1;
+    const snapped = step > 1 ? Math.round(minutes / step) * step : minutes;
+    return Math.max(floor, Math.min(ceiling, snapped));
+}
+/**
+ * Moves by whole steps. Stops at the bounds instead of wrapping — a stepper
+ * that rolls 23:55 round to 00:00 turns a late meeting into an early one.
+ */
+export function stepTime(value, direction, step = 1, min, max) {
+    const current = parseTime(value) ?? clampTime(0, min, max, step);
+    return formatTime(clampTime(current + direction * step, min, max, step));
+}
+/**
+ * `13:05` as the locale writes it — `1:05 PM` in en-US, `13.05` in id-ID.
+ *
+ * Display only. The bound value stays `HH:MM` whatever this returns, because a
+ * localised string is not something a form can post.
+ */
+export function formatClock(value, locale, hour12) {
+    const minutes = parseTime(value);
+    if (minutes === null)
+        return '';
+    const date = new Date(2000, 0, 1, Math.floor(minutes / 60), minutes % 60);
+    return new Intl.DateTimeFormat(locale, { hour: '2-digit', minute: '2-digit', hour12 }).format(date);
+}

package/dist/core/toast.svelte.d.ts

@@ -8,6 +8,7 @@
  *   const id = toast.loading('Rendering…');
  *   toast.dismiss(id);
  */
+import type { Snippet } from 'svelte';
 import type { Tone } from './tones.js';
 export interface ToastAction {
     label: string;
@@ -19,6 +20,8 @@ export interface ToastOptions {
     /** Milliseconds on screen. `0` keeps it until dismissed. Default 5000. */
     duration?: number;
     action?: ToastAction;
+    /** Replaces the tone's own glyph. */
+    icon?: Snippet;
     /** Swaps the glyph for a spinner and defaults `duration` to 0. */
     loading?: boolean;
 }

package/dist/styles/matte/AccordionItem.svelte

@@ -2,6 +2,7 @@
 	import type { Snippet } from 'svelte';
 	import type { HTMLAttributes } from 'svelte/elements';
 	import { toneText, type Tone } from '../../core/tones.js';
+	import { iconMd } from './icon.js';
 
 	interface Props extends HTMLAttributes<HTMLDetailsElement> {
 		title: string;
@@ -9,6 +10,8 @@
 		tone?: Tone;
 		/** Short text on the right of the summary row. */
 		meta?: string;
+		/** Leading icon on the summary row. */
+		icon?: Snippet;
 		children: Snippet;
 	}
 
@@ -17,6 +20,7 @@
 		open = $bindable(false),
 		tone = 'brand',
 		meta,
+		icon,
 		class: className = '',
 		children,
 		...rest
@@ -27,6 +31,7 @@
 	<summary
 		class="flex cursor-pointer list-none items-center gap-4 py-4 font-sans text-[15px] text-text transition-colors duration-150 ease-brand-out select-none hover:text-text-secondary focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-current [&::-webkit-details-marker]:hidden"
 	>
+		{#if icon}<span class={iconMd}>{@render icon()}</span>{/if}
 		<span class="flex-1 font-medium">{title}</span>
 		{#if meta}<span class="font-mono text-xs text-text-muted">{meta}</span>{/if}
 		<svg

package/dist/styles/matte/AccordionItem.svelte.d.ts

@@ -7,6 +7,8 @@ interface Props extends HTMLAttributes<HTMLDetailsElement> {
     tone?: Tone;
     /** Short text on the right of the summary row. */
     meta?: string;
+    /** Leading icon on the summary row. */
+    icon?: Snippet;
     children: Snippet;
 }
 declare const AccordionItem: import("svelte").Component<Props, {}, "open">;

package/dist/styles/matte/Avatar.svelte

@@ -1,4 +1,5 @@
 <script lang="ts">
+	import type { Snippet } from 'svelte';
 	import type { HTMLAttributes } from 'svelte/elements';
 	import { toneSoft, type Tone } from '../../core/tones.js';
 
@@ -13,6 +14,8 @@
 		tone?: Tone;
 		/** Square instead of the default circle. */
 		squared?: boolean;
+		/** Drawn instead of the initials when there is no `src` — a user mark. */
+		fallback?: Snippet;
 	}
 
 	let {
@@ -22,6 +25,7 @@
 		size = 'md',
 		tone = 'brand',
 		squared = false,
+		fallback,
 		class: className = '',
 		...rest
 	}: Props = $props();
@@ -34,6 +38,15 @@
 		xl: 'size-16 text-lg'
 	};
 
+	// The mark tracks the initials: about half the circle, whatever the size.
+	const glyphs: Record<AvatarSize, string> = {
+		xs: 'grid place-items-center *:size-3',
+		sm: 'grid place-items-center *:size-4',
+		md: 'grid place-items-center *:size-5',
+		lg: 'grid place-items-center *:size-6',
+		xl: 'grid place-items-center *:size-8'
+	};
+
 	const initials = $derived(
 		name
 			.trim()
@@ -52,6 +65,8 @@
 >
 	{#if src}
 		<img {src} alt={alt ?? name} class="size-full object-cover" />
+	{:else if fallback}
+		<span class={glyphs[size]}>{@render fallback()}</span>
 	{:else}
 		{initials}
 	{/if}

package/dist/styles/matte/Avatar.svelte.d.ts

@@ -1,3 +1,4 @@
+import type { Snippet } from 'svelte';
 import type { HTMLAttributes } from 'svelte/elements';
 import { type Tone } from '../../core/tones.js';
 export type AvatarSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
@@ -10,6 +11,8 @@ interface Props extends HTMLAttributes<HTMLSpanElement> {
     tone?: Tone;
     /** Square instead of the default circle. */
     squared?: boolean;
+    /** Drawn instead of the initials when there is no `src` — a user mark. */
+    fallback?: Snippet;
 }
 declare const Avatar: import("svelte").Component<Props, {}, "">;
 type Avatar = ReturnType<typeof Avatar>;

package/dist/styles/matte/Badge.svelte

@@ -9,6 +9,7 @@
 		toneText,
 		type Tone
 	} from '../../core/tones.js';
+	import { iconSm } from './icon.js';
 
 	export type BadgeVariant = 'soft' | 'solid' | 'outline';
 	export type BadgeSize = 'sm' | 'md';
@@ -19,6 +20,8 @@
 		size?: BadgeSize;
 		/** Small filled circle before the label. */
 		dot?: boolean;
+		/** Leading icon, 14px — sits where the dot would. */
+		icon?: Snippet;
 		children: Snippet;
 	}
 
@@ -27,6 +30,7 @@
 		variant = 'soft',
 		size = 'md',
 		dot = false,
+		icon,
 		class: className = '',
 		children,
 		...rest
@@ -54,5 +58,6 @@
 			class="size-1.5 shrink-0 rounded-full {variant === 'solid' ? 'bg-current' : toneFill[tone]}"
 		></span>
 	{/if}
+	{#if icon}<span class={iconSm}>{@render icon()}</span>{/if}
 	{@render children()}
 </span>

package/dist/styles/matte/Badge.svelte.d.ts

@@ -9,6 +9,8 @@ interface Props extends HTMLAttributes<HTMLSpanElement> {
     size?: BadgeSize;
     /** Small filled circle before the label. */
     dot?: boolean;
+    /** Leading icon, 14px — sits where the dot would. */
+    icon?: Snippet;
     children: Snippet;
 }
 declare const Badge: import("svelte").Component<Props, {}, "">;

package/dist/styles/matte/Breadcrumb.svelte

@@ -1,11 +1,15 @@
 <script lang="ts">
+	import type { Snippet } from 'svelte';
 	import type { HTMLAttributes } from 'svelte/elements';
 	import { toneHoverText, type Tone } from '../../core/tones.js';
 	import { useLocale } from '../../core/locale.svelte.js';
+	import { iconMd } from './icon.js';
 
 	export interface BreadcrumbItem {
 		label: string;
 		href?: string;
+		/** Leading icon — a home mark on the first crumb, say. */
+		icon?: Snippet;
 	}
 
 	interface Props extends HTMLAttributes<HTMLElement> {
@@ -29,15 +33,18 @@
 				{#if item.href && i < items.length - 1}
 					<a
 						href={item.href}
-						class="text-text-secondary transition-colors duration-150 ease-brand-out {toneHoverText[
+						class="inline-flex items-center gap-1.5 text-text-secondary transition-colors duration-150 ease-brand-out {toneHoverText[
 							tone
 						]}"
 					>
-						{item.label}
+						{#if item.icon}<span class={iconMd}>{@render item.icon()}</span>{/if}{item.label}
 					</a>
 				{:else}
-					<span class="text-text" aria-current={i === items.length - 1 ? 'page' : undefined}>
-						{item.label}
+					<span
+						class="inline-flex items-center gap-1.5 text-text"
+						aria-current={i === items.length - 1 ? 'page' : undefined}
+					>
+						{#if item.icon}<span class={iconMd}>{@render item.icon()}</span>{/if}{item.label}
 					</span>
 				{/if}
 			</li>

package/dist/styles/matte/Breadcrumb.svelte.d.ts

@@ -1,8 +1,11 @@
+import type { Snippet } from 'svelte';
 import type { HTMLAttributes } from 'svelte/elements';
 import { type Tone } from '../../core/tones.js';
 export interface BreadcrumbItem {
     label: string;
     href?: string;
+    /** Leading icon — a home mark on the first crumb, say. */
+    icon?: Snippet;
 }
 interface Props extends HTMLAttributes<HTMLElement> {
     items: BreadcrumbItem[];