@sepale/components 0.0.0-stage → 0.1.0

package/dist/components/DataControl.svelte.d.ts

@@ -0,0 +1,143 @@
+/** What .data-control is made of, classified. The props follow the
+    families the project registers (variants.ts, ADR 0015).
+
+    The control draws its own rows: every class below the root that is
+    not an axis is a PART. The buttons, fields, chips and pagination in
+    them are the kit's own components. */
+export declare const PREFIX = "data-control";
+export declare const AXES: {
+    readonly size: readonly ["xs", "sm", "md", "lg", "xl"];
+    readonly variant: readonly ["boxed"];
+};
+export declare const FLAGS: {};
+export declare const PARTS: readonly ["bar", "bar-left", "bar-right", "search", "count", "filters", "filter", "filter-remove", "editor", "field", "field-label", "more", "actions-start", "actions-end", "actions", "page-options", "pagination", "range", "body", "total"];
+/** Every text the control writes. */
+export interface DataControlLabels {
+    filters: string;
+    sort: string;
+    noSort: string;
+    search: string;
+    perPage: (n: number) => string;
+    selected: (n: number) => string;
+    range: (from: number, to: number, total: number) => string;
+    results: (total: number) => string;
+    save: string;
+    undo: string;
+    redo: string;
+    reset: string;
+    delete: string;
+    add: string;
+    export: string;
+    removeFilter: (title: string) => string;
+    yes: string;
+    no: string;
+    any: string;
+    confirmDeleteTitle: (n: number) => string;
+    confirmDeleteText: string;
+    cancel: string;
+    confirmDiscardTitle: (n: number) => string;
+    confirmDiscardText: string;
+    discard: string;
+    stay: string;
+}
+export declare const LABELS: DataControlLabels;
+/**
+     * The controls of a data handler, around the view that shows its rows:
+     * filters, sort, search, page size, pagination, and actions on the
+     * selection or on the whole resource. Every one of them is optional, and
+     * an action only appears when the handler can do it (`update`, `delete`).
+     *
+     * Deleting and dropping unsaved changes are confirmed in a Dialog, unless
+     * the handler was given its own `confirmDelete` / `confirmDiscard`.
+     */
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+import type { DataHandlerState, EntitySuggestion, Filter, HandledFilter } from './data-handler.svelte.js';
+declare function $$render<F extends readonly Filter[], Model extends Record<string, any>, Id>(): {
+    props: {
+        readonly size?: "xs" | "sm" | "md" | "lg" | "xl" | undefined;
+        readonly variant?: "boxed" | undefined;
+    } & {} & {
+        background?: string;
+    } & Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
+        /** The handler whose rows and requests these controls drive. */
+        handler: DataHandlerState<F, Model, Id>;
+        /** The view: a Table, a Grid, a List — given the handler. */
+        children?: Snippet<[DataHandlerState<F, Model, Id>]>;
+        /** Offer the handler's filters. Default true. */
+        filters?: boolean;
+        /** Draw every filter as a field in the bar, and the page size and the sort
+            with the pagination, instead of a menu, chips and a select in the bar. */
+        fields?: boolean;
+        /** Offer the handler's sorts. Default true. */
+        sorts?: boolean;
+        /** Draw the filter, sort and save buttons as icons alone, their text as a title, and the menus and filters small. The sort in use and the number of results go with the filters. */
+        compact?: boolean;
+        /** Draw a search field. Default true. */
+        search?: boolean;
+        /** Milliseconds without typing before the search is fetched. Default 300. */
+        searchDelay?: number;
+        /** The page sizes to choose from, or `false` for none. */
+        limits?: number[] | false;
+        /** Where the pagination goes. Default `bottom`. */
+        pagination?: "top" | "bottom" | "both" | "none";
+        /** Draw save, undo, redo and discard, when the handler can update. Default true. */
+        editing?: boolean;
+        /** Draw delete, when the handler can delete. Default true. */
+        removable?: boolean;
+        /** Draw export: `true`, or the options the export runs with. */
+        exportable?: boolean | ({
+            name?: string;
+            max?: number;
+            batch?: number;
+            columns?: {
+                key: string;
+                label?: string;
+            }[];
+            format?: ((row: Model) => Record<string, unknown>) | undefined;
+            separator?: string;
+            decimal?: string;
+            download?: boolean;
+        } | undefined);
+        /** Draw an add button calling this. */
+        onAdd?: () => void;
+        /** Confirm deletions and discarded changes in a dialog. Default true. */
+        confirm?: boolean;
+        /** How an entity is drawn, in its filter's chip and suggestions. Default: its text. */
+        entity?: Snippet<[HandledFilter, EntitySuggestion]>;
+        /** Drawn first in the bar, before the filters. */
+        start?: Snippet<[DataHandlerState<F, Model, Id>]>;
+        /** Drawn at the start of the bar, after the filters and the sort. */
+        leftActions?: Snippet<[DataHandlerState<F, Model, Id>]>;
+        /** Drawn at the end of the bar, after the built-in actions. */
+        rightActions?: Snippet<[DataHandlerState<F, Model, Id>]>;
+        /** Drawn above the view (and above a top pagination). */
+        header?: Snippet<[DataHandlerState<F, Model, Id>]>;
+        /** Drawn below the view (and below a bottom pagination). */
+        footer?: Snippet<[DataHandlerState<F, Model, Id>]>;
+        /** The texts, for another language. */
+        labels?: Partial<DataControlLabels>;
+        class?: string;
+    };
+    exports: {};
+    bindings: "";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<F extends readonly Filter[], Model extends Record<string, any>, Id> {
+    props(): ReturnType<typeof $$render<F, Model, Id>>['props'];
+    events(): ReturnType<typeof $$render<F, Model, Id>>['events'];
+    slots(): ReturnType<typeof $$render<F, Model, Id>>['slots'];
+    bindings(): "";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <F extends readonly Filter[], Model extends Record<string, any>, Id>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<F, Model, Id>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<F, Model, Id>['props']>, ReturnType<__sveltets_Render<F, Model, Id>['events']>, ReturnType<__sveltets_Render<F, Model, Id>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<F, Model, Id>['bindings']>;
+    } & ReturnType<__sveltets_Render<F, Model, Id>['exports']>;
+    <F extends readonly Filter[], Model extends Record<string, any>, Id>(internal: unknown, props: ReturnType<__sveltets_Render<F, Model, Id>['props']> & {}): ReturnType<__sveltets_Render<F, Model, Id>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any, any, any>['bindings']>;
+}
+declare const DataControl: $$IsomorphicComponent;
+type DataControl<F extends readonly Filter[], Model extends Record<string, any>, Id> = InstanceType<typeof DataControl<F, Model, Id>>;
+export default DataControl;

package/dist/components/DataHandler.svelte

@@ -0,0 +1,67 @@
+<script module lang="ts">
+	/* No PREFIX, no AXES: the data handler draws nothing, so it has no
+	   namespace and nothing for a family to style. The class is exported for use without the
+	   component: `new DataHandlerState({ … })`. */
+	export {
+		DataHandlerState,
+		parseQuery,
+		parseFilterValues,
+		filterValuesToParams,
+		type DataHandlerOptions,
+		type DataHandlerMessages,
+		type DataRow,
+		type DiscardChoice,
+		type EntityValue,
+		type EntitySuggestion,
+		type Filter,
+		type FilterValues,
+		type GetParams,
+		type GetResult,
+		type HandledFilter,
+		type Identifier,
+		type Navigation,
+		type Sort
+	} from './data-handler.svelte.js';
+</script>
+
+<script
+	lang="ts"
+	generics="const F extends readonly Filter[], Model extends Record<string, any>, Id = string"
+>
+	/**
+	 * The live state of one remote resource, handed to its children. Renders
+	 * nothing of its own: whatever the children draw — a DataControl, a Table,
+	 * a Grid — reads and changes the resource through the handler they are
+	 * given.
+	 *
+	 * The handler is built once, from the props as they are on mount: changing
+	 * a prop afterwards does not rebuild it (that would drop the rows, the
+	 * selection and the edits). Talk to the handler instead.
+	 */
+	import { onMount, untrack, type Snippet } from 'svelte';
+	import {
+		DataHandlerState,
+		type DataHandlerOptions,
+		type Filter
+	} from './data-handler.svelte.js';
+
+	interface Props extends DataHandlerOptions<F, Model, Id> {
+		/** What to draw with the handler. */
+		children?: Snippet<[DataHandlerState<F, Model, Id>]>;
+		/** The handler itself, for the parent. Bindable, read only. */
+		handler?: DataHandlerState<F, Model, Id>;
+		/** Fetch on mount when no `init` was given. Default true. */
+		autoload?: boolean;
+	}
+
+	let { children, handler = $bindable(), autoload = true, ...options }: Props = $props();
+
+	const instance = untrack(() => new DataHandlerState<F, Model, Id>({ ...options } as DataHandlerOptions<F, Model, Id>));
+	handler = instance;
+
+	onMount(() => {
+		if (autoload && !options.init) instance.load({ replace: true });
+	});
+</script>
+
+{@render children?.(instance)}

package/dist/components/DataHandler.svelte.d.ts

@@ -0,0 +1,44 @@
+export { DataHandlerState, parseQuery, parseFilterValues, filterValuesToParams, type DataHandlerOptions, type DataHandlerMessages, type DataRow, type DiscardChoice, type EntityValue, type EntitySuggestion, type Filter, type FilterValues, type GetParams, type GetResult, type HandledFilter, type Identifier, type Navigation, type Sort } from './data-handler.svelte.js';
+/**
+     * The live state of one remote resource, handed to its children. Renders
+     * nothing of its own: whatever the children draw — a DataControl, a Table,
+     * a Grid — reads and changes the resource through the handler they are
+     * given.
+     *
+     * The handler is built once, from the props as they are on mount: changing
+     * a prop afterwards does not rebuild it (that would drop the rows, the
+     * selection and the edits). Talk to the handler instead.
+     */
+import { type Snippet } from 'svelte';
+import { DataHandlerState, type DataHandlerOptions, type Filter } from './data-handler.svelte.js';
+declare function $$render<const F extends readonly Filter[], Model extends Record<string, any>, Id = string>(): {
+    props: DataHandlerOptions<F, Model, Id> & {
+        /** What to draw with the handler. */
+        children?: Snippet<[DataHandlerState<F, Model, Id>]>;
+        /** The handler itself, for the parent. Bindable, read only. */
+        handler?: DataHandlerState<F, Model, Id>;
+        /** Fetch on mount when no `init` was given. Default true. */
+        autoload?: boolean;
+    };
+    exports: {};
+    bindings: "handler";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<const F extends readonly Filter[], Model extends Record<string, any>, Id = string> {
+    props(): ReturnType<typeof $$render<F, Model, Id>>['props'];
+    events(): ReturnType<typeof $$render<F, Model, Id>>['events'];
+    slots(): ReturnType<typeof $$render<F, Model, Id>>['slots'];
+    bindings(): "handler";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <const F extends readonly Filter[], Model extends Record<string, any>, Id = string>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<F, Model, Id>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<F, Model, Id>['props']>, ReturnType<__sveltets_Render<F, Model, Id>['events']>, ReturnType<__sveltets_Render<F, Model, Id>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<F, Model, Id>['bindings']>;
+    } & ReturnType<__sveltets_Render<F, Model, Id>['exports']>;
+    <const F extends readonly Filter[], Model extends Record<string, any>, Id = string>(internal: unknown, props: ReturnType<__sveltets_Render<F, Model, Id>['props']> & {}): ReturnType<__sveltets_Render<F, Model, Id>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any, any, any>['bindings']>;
+}
+declare const DataHandler: $$IsomorphicComponent;
+type DataHandler<const F extends readonly Filter[], Model extends Record<string, any>, Id = string> = InstanceType<typeof DataHandler<F, Model, Id>>;
+export default DataHandler;

package/dist/components/DatePicker.svelte

@@ -0,0 +1,185 @@
+<script lang="ts">
+	/**
+	 * A field that opens a calendar: an Input, a Dropdown and an inline
+	 * Calendar, put together. It draws nothing of its own — no namespace —
+	 * so it looks like the family's input, dropdown and calendar.
+	 *
+	 * The value lives in a real `<input type="date">` (`datetime-local`,
+	 * `time`), visually hidden: it carries `name`, `required`, `min` and
+	 * `max`, so a form submits and validates it as the browser does, and the
+	 * page says what the field holds. The visible field is read only and
+	 * shows `format(value)`; the calendar only writes into the native one.
+	 * When the browser finds it invalid, the visible field shows why.
+	 *
+	 * `value` is a Date, or `[start, end]` with `range` (then the native
+	 * input is a text one holding `start/end`). A single date closes the box
+	 * on its pick, a range on its second date; with a time, the box stays
+	 * open while the time is set.
+	 */
+	import type { ComponentProps } from 'svelte';
+	import Input from './Input.svelte';
+	import Dropdown from './Dropdown.svelte';
+	import Calendar from './Calendar.svelte';
+
+	type Value = Date | Date[] | null;
+	type Kind = 'date' | 'datetime-local' | 'time';
+
+	interface Props {
+		/** The picked date, or [start, end] with `range`. Bindable. */
+		value?: Value;
+		/** A day (default), a day and a time, or a time alone. */
+		type?: Kind;
+		/** Pick a start and an end. Days only. */
+		range?: boolean;
+		/** On the visible field, for a `<label for>`. */
+		id?: string;
+		/** For a form: the native input's name. */
+		name?: string;
+		/** A value is needed: the native input says so to its form. */
+		required?: boolean;
+		placeholder?: string;
+		disabled?: boolean;
+		min?: Date;
+		max?: Date;
+		/** How a value is written in the field. Defaults to the browser's locale for the type. */
+		format?: (date: Date) => string;
+		/** After every completed pick, and after a clear (`null`). */
+		onChange?: (value: Value) => void;
+		/** Colour the field by its validity, as Input's `validator`. */
+		validator?: boolean;
+		/** An error from outside, as on Input: shown, and the field is invalid. */
+		error?: string | null;
+		/** Anything else the Calendar takes: locale, firstDay, view… */
+		calendar?: Partial<ComponentProps<typeof Calendar>>;
+		/** The field's size, as Input's. */
+		size?: ComponentProps<typeof Input>['size'];
+		class?: string;
+	}
+
+	let {
+		value = $bindable(null),
+		type = 'date',
+		range = false,
+		id,
+		name,
+		required = false,
+		placeholder,
+		disabled = false,
+		min,
+		max,
+		format,
+		onChange,
+		validator = false,
+		error = null,
+		calendar = {},
+		size,
+		class: klass = ''
+	}: Props = $props();
+
+	let open = $state(false);
+	/** The browser's message once it found the native input invalid. */
+	let refused = $state<string | null>(null);
+
+	let ranged = $derived(range && type === 'date');
+	let timed = $derived(type !== 'date');
+
+	const list = (v: Value): Date[] => (v == null ? [] : Array.isArray(v) ? v : [v]);
+	const pad = (n: number) => String(n).padStart(2, '0');
+	const day = (d: Date) => `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+	const clock = (d: Date) => `${pad(d.getHours())}:${pad(d.getMinutes())}`;
+
+	/** A date as the native input writes it. */
+	function serial(d: Date): string {
+		if (type === 'time') return clock(d);
+		if (type === 'datetime-local') return `${day(d)}T${clock(d)}`;
+		return day(d);
+	}
+
+	function shown(d: Date): string {
+		if (format) return format(d);
+		if (type === 'time') return d.toLocaleTimeString(undefined, { hour: '2-digit', minute: '2-digit' });
+		if (type === 'datetime-local') return d.toLocaleString(undefined, { dateStyle: 'short', timeStyle: 'short' });
+		return d.toLocaleDateString();
+	}
+
+	let text = $derived(list(value).map(shown).join(' – '));
+	let submitted = $derived(list(value).map(serial).join('/'));
+
+	/* The native input checks `min` and `max` itself, written as it reads them.
+	   A range is a text input: only `required` is checked there. */
+	let bounds = $derived({
+		min: min && !ranged ? serial(min) : undefined,
+		max: max && !ranged ? serial(max) : undefined
+	});
+
+	function picked(next: Value) {
+		value = next;
+		refused = null;
+		const done = ranged ? list(next).length === 2 : next != null;
+		if (done) {
+			if (!timed) open = false;
+			onChange?.(next);
+		}
+	}
+
+	function clear() {
+		value = null;
+		refused = null;
+		onChange?.(null);
+	}
+</script>
+
+<span class={klass} style="position: relative; display: inline-block;">
+	<Dropdown bind:open>
+		{#snippet trigger({ props })}
+			<Input
+				{...props}
+				{id}
+				{size}
+				{placeholder}
+				{disabled}
+				{validator}
+				error={error || refused}
+				value={text}
+				readonly
+				aria-haspopup="dialog"
+				aria-required={required || undefined}
+				onkeydown={(e: KeyboardEvent) => {
+					if (e.key === 'Enter' || e.key === ' ' || e.key === 'ArrowDown') {
+						e.preventDefault();
+						props.onclick();
+					} else if ((e.key === 'Backspace' || e.key === 'Delete') && value != null) {
+						e.preventDefault();
+						clear();
+					}
+				}}
+			/>
+		{/snippet}
+		<Calendar
+			{...calendar}
+			range={ranged}
+			timepicker={timed}
+			options={type === 'time' ? { onlyTimepicker: true, ...calendar.options } : calendar.options}
+			{min}
+			{max}
+			{value}
+			onChange={picked}
+		/>
+	</Dropdown>
+	<!-- What the field holds, as the browser reads it: the form's value and
+	     its validity. Out of sight and out of the tab order; when the browser
+	     finds it invalid, the visible field shows the message. -->
+	<input
+		type={ranged ? 'text' : type}
+		{name}
+		{required}
+		{disabled}
+		min={bounds.min}
+		max={bounds.max}
+		value={submitted}
+		tabindex="-1"
+		aria-hidden="true"
+		style="position: absolute; inset-inline-start: 0; inset-block-end: 0; width: 1px; height: 1px; opacity: 0; pointer-events: none;"
+		oninvalid={(e) => (refused = e.currentTarget.validationMessage)}
+	/>
+</span>

package/dist/components/DatePicker.svelte.d.ts

@@ -0,0 +1,56 @@
+/**
+     * A field that opens a calendar: an Input, a Dropdown and an inline
+     * Calendar, put together. It draws nothing of its own — no namespace —
+     * so it looks like the family's input, dropdown and calendar.
+     *
+     * The value lives in a real `<input type="date">` (`datetime-local`,
+     * `time`), visually hidden: it carries `name`, `required`, `min` and
+     * `max`, so a form submits and validates it as the browser does, and the
+     * page says what the field holds. The visible field is read only and
+     * shows `format(value)`; the calendar only writes into the native one.
+     * When the browser finds it invalid, the visible field shows why.
+     *
+     * `value` is a Date, or `[start, end]` with `range` (then the native
+     * input is a text one holding `start/end`). A single date closes the box
+     * on its pick, a range on its second date; with a time, the box stays
+     * open while the time is set.
+     */
+import type { ComponentProps } from 'svelte';
+import Input from './Input.svelte';
+import Calendar from './Calendar.svelte';
+type Value = Date | Date[] | null;
+type Kind = 'date' | 'datetime-local' | 'time';
+interface Props {
+    /** The picked date, or [start, end] with `range`. Bindable. */
+    value?: Value;
+    /** A day (default), a day and a time, or a time alone. */
+    type?: Kind;
+    /** Pick a start and an end. Days only. */
+    range?: boolean;
+    /** On the visible field, for a `<label for>`. */
+    id?: string;
+    /** For a form: the native input's name. */
+    name?: string;
+    /** A value is needed: the native input says so to its form. */
+    required?: boolean;
+    placeholder?: string;
+    disabled?: boolean;
+    min?: Date;
+    max?: Date;
+    /** How a value is written in the field. Defaults to the browser's locale for the type. */
+    format?: (date: Date) => string;
+    /** After every completed pick, and after a clear (`null`). */
+    onChange?: (value: Value) => void;
+    /** Colour the field by its validity, as Input's `validator`. */
+    validator?: boolean;
+    /** An error from outside, as on Input: shown, and the field is invalid. */
+    error?: string | null;
+    /** Anything else the Calendar takes: locale, firstDay, view… */
+    calendar?: Partial<ComponentProps<typeof Calendar>>;
+    /** The field's size, as Input's. */
+    size?: ComponentProps<typeof Input>['size'];
+    class?: string;
+}
+declare const DatePicker: import("svelte").Component<Props, {}, "value">;
+type DatePicker = ReturnType<typeof DatePicker>;
+export default DatePicker;