@nqmcreative/ui 0.3.0 → 0.4.0

package/dist/core/color.js

@@ -0,0 +1,39 @@
+/**
+ * Hex colours for the colour field.
+ *
+ * Only hex: it is the one notation `<input type="color">` accepts and the one
+ * every design tool copies to the clipboard. Anything else the app can convert
+ * before it binds.
+ */
+const HEX = /^#?([0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+/**
+ * `abc`, `#ABC`, `#aabbcc` → `#aabbcc`. Returns `null` when it is not a hex
+ * colour, so a half-typed value can be left alone rather than corrected under
+ * the caret.
+ *
+ * Shorthand is expanded and alpha is dropped: the native swatch understands
+ * neither, and a value the swatch cannot show is worse than a rounded one.
+ */
+export function normaliseHex(text) {
+    const match = HEX.exec(text.trim());
+    if (!match)
+        return null;
+    let digits = match[1].toLowerCase();
+    if (digits.length <= 4)
+        digits = [...digits].map((digit) => digit + digit).join('');
+    return `#${digits.slice(0, 6)}`;
+}
+/**
+ * True when a colour is dark enough to want light text on top of it.
+ *
+ * Rec. 601 luma rather than WCAG relative luminance — the threshold is for
+ * picking one of two label colours on a swatch, not for proving a contrast
+ * ratio, and this is the version everyone's design tokens are tuned against.
+ */
+export function isDark(hex) {
+    const value = normaliseHex(hex);
+    if (!value)
+        return false;
+    const [r, g, b] = [1, 3, 5].map((at) => parseInt(value.slice(at, at + 2), 16));
+    return (r * 299 + g * 587 + b * 114) / 1000 < 140;
+}

package/dist/core/index.d.ts

@@ -25,7 +25,14 @@ export { pageRange } from './pagination.js';
 export { sortFiles, matchesAccept, formatSize } from './files.js';
 export type { RejectedFile, FileRules } from './files.js';
 export { passwordScore } from './password.js';
-export { clampToStep, percentOf, stepDecimals } from './number.js';
+export { clampToStep, formatGrouped, parseGrouped, percentOf, stepDecimals } from './number.js';
+export type { GroupOptions } from './number.js';
+export { caretIndex, clearFrom, fillFrom, sanitisePin } from './pin.js';
+export type { PinMode } from './pin.js';
+export { addTag, splitTags } from './tags.js';
+export type { TagRules, TagRejection } from './tags.js';
+export { normaliseHex, isDark } from './color.js';
+export { MINUTES_IN_DAY, clampTime, formatClock, formatTime, parseTime, stepTime } from './time.js';
 export { toISO, fromISO, today, isSameDay, addDays, addMonths, monthGrid, weekdayNames, monthLabel, isOutOfRange, formatISO, parseFormatted } from './date.js';
 export type { DateFormat } from './date.js';
 export { calendarKeyMove, dateHint } from './calendar.js';

package/dist/core/index.js

@@ -23,7 +23,11 @@ export { nextSort, sortRows, toggleKey } from './table.js';
 export { pageRange } from './pagination.js';
 export { sortFiles, matchesAccept, formatSize } from './files.js';
 export { passwordScore } from './password.js';
-export { clampToStep, percentOf, stepDecimals } from './number.js';
+export { clampToStep, formatGrouped, parseGrouped, percentOf, stepDecimals } from './number.js';
+export { caretIndex, clearFrom, fillFrom, sanitisePin } from './pin.js';
+export { addTag, splitTags } from './tags.js';
+export { normaliseHex, isDark } from './color.js';
+export { MINUTES_IN_DAY, clampTime, formatClock, formatTime, parseTime, stepTime } from './time.js';
 /* --- dates --- */
 export { toISO, fromISO, today, isSameDay, addDays, addMonths, monthGrid, weekdayNames, monthLabel, isOutOfRange, formatISO, parseFormatted } from './date.js';
 export { calendarKeyMove, dateHint } from './calendar.js';

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/styles/matte/ColorInput.svelte

@@ -0,0 +1,110 @@
+<script lang="ts">
+	import type { HTMLInputAttributes } from 'svelte/elements';
+	import { normaliseHex } from '../../core/color.js';
+	import { useLocale } from '../../core/locale.svelte.js';
+	import type { Tone } from '../../core/tones.js';
+	import Input, { type InputSize } from './Input.svelte';
+
+	interface Props extends Omit<HTMLInputAttributes, 'size' | 'prefix' | 'suffix' | 'type'> {
+		/** Bindable `#rrggbb`. Shorthand and alpha are normalised away on blur. */
+		value?: string;
+		size?: InputSize;
+		tone?: Tone;
+		invalid?: boolean;
+		/** Fixed choices under the field. Empty hides the row. */
+		swatches?: string[];
+		class?: string;
+	}
+
+	let {
+		value = $bindable('#000000'),
+		size = 'md',
+		tone = 'brand',
+		invalid = false,
+		disabled = false,
+		swatches = [],
+		class: className = '',
+		...rest
+	}: Props = $props();
+
+	const t = useLocale();
+
+	// The text can be mid-typing (`#a2`) while the swatch needs a real colour,
+	// so the swatch follows the last value that parsed rather than the field.
+	let text = $state('');
+	let editing = $state(false);
+
+	$effect(() => {
+		if (!editing) text = value;
+	});
+
+	const resolved = $derived(normaliseHex(text) ?? normaliseHex(value) ?? '#000000');
+
+	// Same reason as CurrencyInput: at input time the bound `text` is one
+	// keystroke behind, so the element is the only current source.
+	function onText(event: Event & { currentTarget: HTMLInputElement }) {
+		const hex = normaliseHex(event.currentTarget.value);
+		if (hex) value = hex;
+	}
+
+	function settle() {
+		editing = false;
+		value = normaliseHex(text) ?? value;
+		text = value;
+	}
+
+	function choose(hex: string) {
+		value = normaliseHex(hex) ?? value;
+		text = value;
+	}
+</script>
+
+<div class="flex w-full flex-col gap-2 {className}">
+	<Input
+		bind:value={text}
+		{size}
+		{tone}
+		{invalid}
+		{disabled}
+		spellcheck="false"
+		autocapitalize="none"
+		placeholder="#000000"
+		oninput={onText}
+		onfocus={() => (editing = true)}
+		onblur={settle}
+		class="[&_input]:font-mono [&_input]:uppercase"
+		{...rest}
+	>
+		{#snippet prefix()}
+			<span class="relative grid size-5 place-items-center border border-hairline">
+				<span class="absolute inset-0" style="background-color: {resolved}"></span>
+				<input
+					type="color"
+					value={resolved}
+					{disabled}
+					aria-label={t.current.pickColour}
+					oninput={(event) => choose(event.currentTarget.value)}
+					class="absolute inset-0 cursor-pointer opacity-0 disabled:cursor-not-allowed"
+				/>
+			</span>
+		{/snippet}
+	</Input>
+
+	{#if swatches.length}
+		<div class="flex flex-wrap gap-1.5">
+			{#each swatches as swatch (swatch)}
+				<button
+					type="button"
+					{disabled}
+					onclick={() => choose(swatch)}
+					title={swatch}
+					aria-label={swatch}
+					aria-pressed={resolved === normaliseHex(swatch)}
+					class="size-6 border transition-transform duration-150 hover:-translate-y-0.5 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-current disabled:pointer-events-none disabled:opacity-50
+						{resolved === normaliseHex(swatch) ? 'border-text' : 'border-hairline'}"
+					style="background-color: {swatch}"
+				></button>
+			{/each}
+		</div>
+	{/if}
+</div>

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

@@ -0,0 +1,16 @@
+import type { HTMLInputAttributes } from 'svelte/elements';
+import type { Tone } from '../../core/tones.js';
+import { type InputSize } from './Input.svelte';
+interface Props extends Omit<HTMLInputAttributes, 'size' | 'prefix' | 'suffix' | 'type'> {
+    /** Bindable `#rrggbb`. Shorthand and alpha are normalised away on blur. */
+    value?: string;
+    size?: InputSize;
+    tone?: Tone;
+    invalid?: boolean;
+    /** Fixed choices under the field. Empty hides the row. */
+    swatches?: string[];
+    class?: string;
+}
+declare const ColorInput: import("svelte").Component<Props, {}, "value">;
+type ColorInput = ReturnType<typeof ColorInput>;
+export default ColorInput;