@loidolt/theme-svelte 0.4.0 → 0.6.0

package/dist/data-table-utils.d.ts

@@ -0,0 +1,62 @@
+import type { Snippet } from 'svelte';
+import type { ColumnAlign, Option } from './types.js';
+/** A column filter: text is matched as a substring, a list as a set of accepted values. */
+export type DataTableFilterValue = string | string[];
+export interface DataTableColumn<T> {
+    /** Unique within the table; the key for sorting, filtering and visibility. */
+    id: string;
+    /** Column heading, and the column's name in menus. */
+    header: string;
+    /** Where the value comes from. Defaults to `row[id]`. */
+    accessor?: keyof T | ((row: T) => unknown);
+    sortable?: boolean;
+    /** Custom order for this column. Defaults to numbers, then dates, then natural text order. */
+    compare?: (a: T, b: T) => number;
+    align?: ColumnAlign;
+    /** A CSS width for the column. */
+    width?: string;
+    /** Offered in the column-visibility menu. Defaults to `true`. */
+    hideable?: boolean;
+    /** Included in the global search. Defaults to `true`. */
+    searchable?: boolean;
+    /**
+     * Hide the column at and below a breakpoint, so a narrow screen keeps the columns that matter.
+     * The data stays searchable and sortable.
+     */
+    hideBelow?: 'compact' | 'expanded';
+    /** Display text. Defaults to the value as text, with dates as local dates. */
+    format?: (value: unknown, row: T) => string;
+    /** Custom filter test. Defaults to a substring match for text and set membership for lists. */
+    filter?: (row: T, value: DataTableFilterValue) => boolean;
+    /** Choices for a faceted filter. Defaults to the distinct values present in the data. */
+    filterOptions?: Option[];
+    /** Custom cell content. Receives the row's data. */
+    cell?: Snippet<[T]>;
+    /** Allow editing the cell in place. `DataTable` reports edits through `onCellEdit`. */
+    editable?: boolean;
+}
+/** The value a column reads from a row. */
+export declare function cellValue<T>(row: T, column: DataTableColumn<T>): unknown;
+/** The text a cell shows. */
+export declare function formatCell<T>(row: T, column: DataTableColumn<T>): string;
+/**
+ * Ascending order for two cell values: numbers numerically, dates by time, everything else in
+ * natural text order ("Sheet 2" before "Sheet 10"). Empty values always sort last, whichever
+ * the direction, so they never crowd the top of a list.
+ */
+export declare function compareValues(a: unknown, b: unknown): number;
+/**
+ * A comparator for one column. `direction` 1 is ascending, -1 descending; empty values stay at
+ * the end either way.
+ */
+export declare function rowComparator<T>(column: DataTableColumn<T>, direction: 1 | -1): (a: T, b: T) => number;
+/** Sorts a copy of `rows` by one column. */
+export declare function sortRows<T>(rows: readonly T[], column: DataTableColumn<T>, direction: 1 | -1): T[];
+/** Whether a filter is set to anything at all. */
+export declare const isActiveFilter: (value: DataTableFilterValue | null | undefined) => boolean;
+/** The default column filter: a case-insensitive substring for text, membership for a list. */
+export declare function matchesFilter<T>(row: T, column: DataTableColumn<T>, value: DataTableFilterValue): boolean;
+/** Whether any searchable column's text contains `query`. */
+export declare function matchesSearch<T>(row: T, columns: readonly DataTableColumn<T>[], query: string): boolean;
+/** How many rows hold each distinct value of a column — the counts beside a faceted filter. */
+export declare function countValues<T>(rows: readonly T[], column: DataTableColumn<T>): Map<string, number>;

package/dist/data-table-utils.js

@@ -0,0 +1,91 @@
+/** The value a column reads from a row. */
+export function cellValue(row, column) {
+    const { accessor, id } = column;
+    if (typeof accessor === 'function')
+        return accessor(row);
+    return row[(accessor ?? id)];
+}
+/** The text a cell shows. */
+export function formatCell(row, column) {
+    const value = cellValue(row, column);
+    if (column.format)
+        return column.format(value, row);
+    if (value == null)
+        return '';
+    if (value instanceof Date)
+        return Number.isNaN(value.getTime()) ? '' : value.toLocaleDateString();
+    if (Array.isArray(value))
+        return value.join(', ');
+    return String(value);
+}
+const collator = new Intl.Collator(undefined, { numeric: true, sensitivity: 'base' });
+/**
+ * Ascending order for two cell values: numbers numerically, dates by time, everything else in
+ * natural text order ("Sheet 2" before "Sheet 10"). Empty values always sort last, whichever
+ * the direction, so they never crowd the top of a list.
+ */
+export function compareValues(a, b) {
+    if (typeof a === 'number' && typeof b === 'number')
+        return a - b;
+    if (a instanceof Date && b instanceof Date)
+        return a.getTime() - b.getTime();
+    if (typeof a === 'boolean' && typeof b === 'boolean')
+        return Number(a) - Number(b);
+    return collator.compare(String(a), String(b));
+}
+const isEmpty = (value) => value == null || value === '' || (value instanceof Date && Number.isNaN(value.getTime()));
+/**
+ * A comparator for one column. `direction` 1 is ascending, -1 descending; empty values stay at
+ * the end either way.
+ */
+export function rowComparator(column, direction) {
+    return (a, b) => {
+        if (column.compare)
+            return column.compare(a, b) * direction;
+        const [left, right] = [cellValue(a, column), cellValue(b, column)];
+        const [leftEmpty, rightEmpty] = [isEmpty(left), isEmpty(right)];
+        if (leftEmpty || rightEmpty)
+            return Number(leftEmpty) - Number(rightEmpty);
+        return compareValues(left, right) * direction;
+    };
+}
+/** Sorts a copy of `rows` by one column. */
+export function sortRows(rows, column, direction) {
+    return [...rows].sort(rowComparator(column, direction));
+}
+/** Whether a filter is set to anything at all. */
+export const isActiveFilter = (value) => value != null && (Array.isArray(value) ? value.length > 0 : value.trim() !== '');
+/** The default column filter: a case-insensitive substring for text, membership for a list. */
+export function matchesFilter(row, column, value) {
+    if (column.filter)
+        return column.filter(row, value);
+    const raw = cellValue(row, column);
+    if (Array.isArray(value)) {
+        const accepted = new Set(value);
+        return Array.isArray(raw)
+            ? raw.some((item) => accepted.has(String(item)))
+            : accepted.has(String(raw ?? ''));
+    }
+    return formatCell(row, column).toLocaleLowerCase().includes(value.trim().toLocaleLowerCase());
+}
+/** Whether any searchable column's text contains `query`. */
+export function matchesSearch(row, columns, query) {
+    const needle = query.trim().toLocaleLowerCase();
+    if (!needle)
+        return true;
+    return columns.some((column) => column.searchable !== false && formatCell(row, column).toLocaleLowerCase().includes(needle));
+}
+/** How many rows hold each distinct value of a column — the counts beside a faceted filter. */
+export function countValues(rows, column) {
+    const counts = new Map();
+    for (const row of rows) {
+        const raw = cellValue(row, column);
+        for (const item of Array.isArray(raw) ? raw : [raw]) {
+            if (isEmpty(item))
+                continue;
+            const key = String(item);
+            counts.set(key, (counts.get(key) ?? 0) + 1);
+        }
+    }
+    return counts;
+}

package/dist/data-table.svelte.d.ts

@@ -0,0 +1,132 @@
+import { type DataTableColumn, type DataTableFilterValue } from './data-table-utils.js';
+import type { SortDirection } from './types.js';
+export type { DataTableColumn, DataTableFilterValue } from './data-table-utils.js';
+/** The column and direction a table is sorted by. */
+export interface DataTableSort {
+    column: string;
+    direction: Exclude<SortDirection, 'none'>;
+}
+export interface DataTableRow<T> {
+    /** From `getRowId`; stable across sorting, filtering and paging. */
+    id: string;
+    /** Position in `data`. */
+    index: number;
+    original: T;
+    selected: boolean;
+}
+export interface DataTableOptions<T> {
+    /**
+     * The rows. Pass a getter to keep the table in step with changing data:
+     * `createDataTable({ get data() { return rows; }, columns })`.
+     */
+    data: T[];
+    columns: DataTableColumn<T>[];
+    /** Stable id for a row. Defaults to its index in `data`, which does not survive reordering. */
+    getRowId?: (row: T, index: number) => string;
+    initialSort?: DataTableSort;
+    /** Rows per page. `Infinity` turns paging off. */
+    pageSize?: number;
+    initialPage?: number;
+    initialSearch?: string;
+    initialFilters?: Record<string, DataTableFilterValue>;
+    initialHidden?: string[];
+    initialSelected?: string[];
+    /** Row selection. Defaults to `'none'`. */
+    selection?: 'none' | 'single' | 'multiple';
+    isRowSelectable?: (row: T) => boolean;
+    /**
+     * Hand work to a server. A manual step leaves `data` as given — you sort, filter or page it
+     * yourself in the matching callback and pass the result back in.
+     */
+    manual?: {
+        sorting?: boolean;
+        filtering?: boolean;
+        pagination?: boolean;
+    };
+    /** Total rows on the server. Required with manual pagination. */
+    rowCount?: number;
+    onSortChange?: (sort: DataTableSort | null) => void;
+    onSearchChange?: (search: string) => void;
+    onFiltersChange?: (filters: Record<string, DataTableFilterValue>) => void;
+    onPageChange?: (page: {
+        page: number;
+        pageSize: number;
+    }) => void;
+    onSelectionChange?: (selected: string[]) => void;
+    onVisibilityChange?: (hidden: string[]) => void;
+}
+export interface DataTableState<T> {
+    /** The current page of rows. */
+    readonly rows: DataTableRow<T>[];
+    /** Every row that passes search and filters, in sort order, across all pages. */
+    readonly filteredRows: DataTableRow<T>[];
+    /** Visible columns, in order. */
+    readonly columns: DataTableColumn<T>[];
+    readonly allColumns: DataTableColumn<T>[];
+    /** Rows across all pages after filtering — or the server's `rowCount`. */
+    readonly rowCount: number;
+    /** 1-based, so it feeds `Pagination` directly. */
+    readonly page: number;
+    readonly pageSize: number;
+    readonly pageCount: number;
+    readonly sort: DataTableSort | null;
+    readonly search: string;
+    readonly filters: Record<string, DataTableFilterValue>;
+    readonly selection: 'none' | 'single' | 'multiple';
+    readonly selected: string[];
+    readonly selectedCount: number;
+    /** Every selectable row on this page is selected. */
+    readonly allSelected: boolean;
+    /** Some, but not all, selectable rows on this page are selected. */
+    readonly someSelected: boolean;
+    readonly hidden: string[];
+    /** A column's sort state, ready for `TableHeader`'s `sort` prop. */
+    sortOf(columnId: string): SortDirection;
+    /** Sort by a column. Without a direction it goes ascending, then flips on repeat. */
+    sortBy(columnId: string, direction?: DataTableSort['direction']): void;
+    clearSort(): void;
+    setSearch(search: string): void;
+    /** Set a column filter; `null`, `''` or `[]` clears it. */
+    setFilter(columnId: string, value: DataTableFilterValue | null): void;
+    clearFilters(): void;
+    setPage(page: number): void;
+    setPageSize(size: number): void;
+    next(): void;
+    previous(): void;
+    isSelected(rowId: string): boolean;
+    isSelectable(row: DataTableRow<T>): boolean;
+    /** Select, deselect (`on: false`) or toggle a row. In `single` mode selecting clears the rest. */
+    select(rowId: string, on?: boolean): void;
+    /** Select or clear every selectable row on the current page. */
+    toggleAll(on?: boolean): void;
+    clearSelection(): void;
+    isVisible(columnId: string): boolean;
+    setColumnVisible(columnId: string, visible: boolean): void;
+    showAllColumns(): void;
+    /** Counts of each value in a column, among rows passing every *other* filter. */
+    facets(columnId: string): Map<string, number>;
+    /** The text a cell shows. */
+    format(row: T, column: DataTableColumn<T>): string;
+    /** Back to the initial sort, search, filters, page, selection and visibility. */
+    reset(): void;
+}
+/**
+ * Table state without the table: sorting, search, column filters, paging, row selection and
+ * column visibility over an array, in runes. Render it with `DataTable`, or feed its values to
+ * `Table`, `TableHeader` and `Pagination` yourself.
+ *
+ * ```ts
+ * const table = createDataTable({
+ *   get data() { return sheets; },
+ *   columns: [
+ *     { id: 'name', header: 'Name', sortable: true },
+ *     { id: 'layers', header: 'Layers', align: 'end', sortable: true },
+ *   ],
+ *   getRowId: (sheet) => sheet.id,
+ *   pageSize: 25,
+ * });
+ * ```
+ *
+ * Works during SSR and outside components: state is set synchronously and nothing subscribes.
+ */
+export declare function createDataTable<T>(options: DataTableOptions<T>): DataTableState<T>;

package/dist/data-table.svelte.js

@@ -0,0 +1,292 @@
+import { SvelteSet } from 'svelte/reactivity';
+import { countValues, formatCell, isActiveFilter, matchesFilter, matchesSearch, rowComparator, } from './data-table-utils.js';
+const validPageSize = (size) => size === Infinity || (Number.isInteger(size) && size > 0);
+/**
+ * Table state without the table: sorting, search, column filters, paging, row selection and
+ * column visibility over an array, in runes. Render it with `DataTable`, or feed its values to
+ * `Table`, `TableHeader` and `Pagination` yourself.
+ *
+ * ```ts
+ * const table = createDataTable({
+ *   get data() { return sheets; },
+ *   columns: [
+ *     { id: 'name', header: 'Name', sortable: true },
+ *     { id: 'layers', header: 'Layers', align: 'end', sortable: true },
+ *   ],
+ *   getRowId: (sheet) => sheet.id,
+ *   pageSize: 25,
+ * });
+ * ```
+ *
+ * Works during SSR and outside components: state is set synchronously and nothing subscribes.
+ */
+export function createDataTable(options) {
+    const { initialSort, pageSize: initialPageSize = 10, initialPage = 1, initialSearch = '', initialFilters = {}, initialHidden = [], initialSelected = [], manual = {}, } = options;
+    const ids = options.columns.map((column) => column.id);
+    const duplicate = ids.find((id, index) => ids.indexOf(id) !== index);
+    if (duplicate !== undefined) {
+        throw new RangeError(`createDataTable: duplicate column id "${duplicate}"`);
+    }
+    if (!validPageSize(initialPageSize)) {
+        throw new RangeError('createDataTable: `pageSize` must be a positive integer or Infinity');
+    }
+    if (initialSort && !ids.includes(initialSort.column)) {
+        throw new RangeError(`createDataTable: unknown initialSort column "${initialSort.column}"`);
+    }
+    if (manual.pagination && options.rowCount === undefined) {
+        throw new RangeError('createDataTable: manual pagination needs `rowCount`');
+    }
+    let sort = $state(initialSort ?? null);
+    let search = $state(initialSearch);
+    let filters = $state({ ...initialFilters });
+    let page = $state(initialPage);
+    let pageSize = $state(initialPageSize);
+    const selected = new SvelteSet(initialSelected);
+    const hidden = new SvelteSet(initialHidden);
+    const selection = $derived(options.selection ?? 'none');
+    const allColumns = $derived(options.columns);
+    const columns = $derived(allColumns.filter((column) => !hidden.has(column.id)));
+    const getRowId = $derived(options.getRowId ?? ((_row, index) => String(index)));
+    const indexed = $derived(options.data.map((original, index) => ({ id: getRowId(original, index), index, original })));
+    const column = (id) => allColumns.find((one) => one.id === id);
+    /** Rows passing the search and every filter except `skip` (for facet counts). */
+    const passing = (skip) => {
+        if (manual.filtering)
+            return indexed;
+        return indexed.filter(({ original }) => {
+            if (!matchesSearch(original, columns, search))
+                return false;
+            for (const [id, value] of Object.entries(filters)) {
+                if (id === skip || !isActiveFilter(value))
+                    continue;
+                const target = column(id);
+                if (target && !matchesFilter(original, target, value))
+                    return false;
+            }
+            return true;
+        });
+    };
+    const filtered = $derived(passing());
+    const sorted = $derived.by(() => {
+        if (manual.sorting || !sort)
+            return filtered;
+        const target = column(sort.column);
+        if (!target)
+            return filtered;
+        const compare = rowComparator(target, sort.direction === 'ascending' ? 1 : -1);
+        return [...filtered].sort((a, b) => compare(a.original, b.original));
+    });
+    const rowCount = $derived(manual.pagination ? (options.rowCount ?? 0) : sorted.length);
+    const pageCount = $derived(pageSize === Infinity ? 1 : Math.max(1, Math.ceil(rowCount / pageSize)));
+    // Data can shrink under the current page; show the last page that still exists.
+    const currentPage = $derived(Math.min(Math.max(1, page), pageCount));
+    const withSelection = (row) => ({
+        ...row,
+        selected: selected.has(row.id),
+    });
+    const filteredRows = $derived(sorted.map(withSelection));
+    const rows = $derived(manual.pagination || pageSize === Infinity
+        ? filteredRows
+        : filteredRows.slice((currentPage - 1) * pageSize, currentPage * pageSize));
+    const isSelectable = (row) => selection !== 'none' && (options.isRowSelectable?.(row.original) ?? true);
+    const selectableOnPage = $derived(rows.filter(isSelectable));
+    const allSelected = $derived(selectableOnPage.length > 0 && selectableOnPage.every((row) => selected.has(row.id)));
+    const someSelected = $derived(!allSelected && selectableOnPage.some((row) => selected.has(row.id)));
+    const emitPage = () => options.onPageChange?.({ page: currentPage, pageSize });
+    const emitSelection = () => options.onSelectionChange?.([...selected]);
+    const emitVisibility = () => options.onVisibilityChange?.([...hidden]);
+    /** A narrower result set starts over at the first page. */
+    const backToFirstPage = () => {
+        if (page === 1)
+            return;
+        page = 1;
+        emitPage();
+    };
+    function setPage(next) {
+        const clamped = Math.min(Math.max(1, Math.trunc(next) || 1), pageCount);
+        if (clamped === currentPage && clamped === page)
+            return;
+        page = clamped;
+        emitPage();
+    }
+    function select(rowId, on) {
+        if (selection === 'none')
+            return;
+        const next = on ?? !selected.has(rowId);
+        if (next === selected.has(rowId))
+            return;
+        if (next && selection === 'single')
+            selected.clear();
+        if (next)
+            selected.add(rowId);
+        else
+            selected.delete(rowId);
+        emitSelection();
+    }
+    return {
+        get rows() {
+            return rows;
+        },
+        get filteredRows() {
+            return filteredRows;
+        },
+        get columns() {
+            return columns;
+        },
+        get allColumns() {
+            return allColumns;
+        },
+        get rowCount() {
+            return rowCount;
+        },
+        get page() {
+            return currentPage;
+        },
+        get pageSize() {
+            return pageSize;
+        },
+        get pageCount() {
+            return pageCount;
+        },
+        get sort() {
+            return sort;
+        },
+        get search() {
+            return search;
+        },
+        get filters() {
+            return filters;
+        },
+        get selection() {
+            return selection;
+        },
+        get selected() {
+            return [...selected];
+        },
+        get selectedCount() {
+            return selected.size;
+        },
+        get allSelected() {
+            return allSelected;
+        },
+        get someSelected() {
+            return someSelected;
+        },
+        get hidden() {
+            return [...hidden];
+        },
+        sortOf: (columnId) => (sort?.column === columnId ? sort.direction : 'none'),
+        sortBy(columnId, direction) {
+            if (!column(columnId))
+                return;
+            const next = direction ??
+                (sort?.column === columnId && sort.direction === 'ascending' ? 'descending' : 'ascending');
+            sort = { column: columnId, direction: next };
+            options.onSortChange?.(sort);
+        },
+        clearSort() {
+            if (!sort)
+                return;
+            sort = null;
+            options.onSortChange?.(null);
+        },
+        setSearch(next) {
+            if (next === search)
+                return;
+            search = next;
+            options.onSearchChange?.(next);
+            backToFirstPage();
+        },
+        setFilter(columnId, value) {
+            const { [columnId]: previous, ...rest } = filters;
+            if (!isActiveFilter(value) && !isActiveFilter(previous))
+                return;
+            filters = isActiveFilter(value) ? { ...rest, [columnId]: value } : rest;
+            options.onFiltersChange?.(filters);
+            backToFirstPage();
+        },
+        clearFilters() {
+            if (Object.keys(filters).length === 0)
+                return;
+            filters = {};
+            options.onFiltersChange?.(filters);
+            backToFirstPage();
+        },
+        setPage,
+        setPageSize(size) {
+            if (!validPageSize(size)) {
+                throw new RangeError('createDataTable: `pageSize` must be a positive integer or Infinity');
+            }
+            if (size === pageSize)
+                return;
+            pageSize = size;
+            page = 1;
+            emitPage();
+        },
+        next: () => setPage(currentPage + 1),
+        previous: () => setPage(currentPage - 1),
+        isSelected: (rowId) => selected.has(rowId),
+        isSelectable,
+        select,
+        toggleAll(on) {
+            if (selection !== 'multiple')
+                return;
+            const next = on ?? !allSelected;
+            let changed = false;
+            for (const row of selectableOnPage) {
+                if (selected.has(row.id) === next)
+                    continue;
+                if (next)
+                    selected.add(row.id);
+                else
+                    selected.delete(row.id);
+                changed = true;
+            }
+            if (changed)
+                emitSelection();
+        },
+        clearSelection() {
+            if (selected.size === 0)
+                return;
+            selected.clear();
+            emitSelection();
+        },
+        isVisible: (columnId) => !hidden.has(columnId),
+        setColumnVisible(columnId, visible) {
+            if (visible === !hidden.has(columnId))
+                return;
+            if (visible)
+                hidden.delete(columnId);
+            else
+                hidden.add(columnId);
+            emitVisibility();
+        },
+        showAllColumns() {
+            if (hidden.size === 0)
+                return;
+            hidden.clear();
+            emitVisibility();
+        },
+        facets(columnId) {
+            const target = column(columnId);
+            // eslint-disable-next-line svelte/prefer-svelte-reactivity -- a fresh, read-only result
+            if (!target)
+                return new Map();
+            return countValues(passing(columnId).map((row) => row.original), target);
+        },
+        format: (row, target) => formatCell(row, target),
+        reset() {
+            sort = initialSort ?? null;
+            search = initialSearch;
+            filters = { ...initialFilters };
+            page = initialPage;
+            pageSize = initialPageSize;
+            selected.clear();
+            for (const id of initialSelected)
+                selected.add(id);
+            hidden.clear();
+            for (const id of initialHidden)
+                hidden.add(id);
+        },
+    };
+}

package/dist/hls.d.ts

@@ -0,0 +1,35 @@
+/** The slice of the hls.js API the players use. */
+export interface HlsInstance {
+    loadSource(url: string): void;
+    attachMedia(media: HTMLMediaElement): void;
+    startLoad(): void;
+    recoverMediaError(): void;
+    destroy(): void;
+    on(event: string, callback: (event: string, data: HlsErrorData) => void): void;
+}
+export interface HlsErrorData {
+    type?: string;
+    details?: string;
+    fatal?: boolean;
+}
+export interface HlsConstructor {
+    new (config?: Record<string, unknown>): HlsInstance;
+    isSupported(): boolean;
+    readonly Events: {
+        ERROR: string;
+    } & Record<string, string>;
+    readonly ErrorTypes: {
+        NETWORK_ERROR: string;
+        MEDIA_ERROR: string;
+    } & Record<string, string>;
+}
+export type HlsLoader = () => Promise<HlsConstructor> | HlsConstructor;
+/** Registers how to load hls.js — typically a dynamic import. `null` unregisters. */
+export declare function setHlsLoader(loader: HlsLoader | null): void;
+/**
+ * Resolves hls.js through `loader`, else the registered loader, else a global `Hls` from a
+ * script tag. Resolves `null` rather than rejecting when none is available.
+ */
+export declare function loadHls(loader?: HlsLoader): Promise<HlsConstructor | null>;
+/** Whether the browser plays HLS without hls.js (Safari, iOS). */
+export declare function canPlayHlsNatively(media?: HTMLMediaElement | null): boolean;

package/dist/hls.js

@@ -0,0 +1,37 @@
+/*
+ * HLS (`.m3u8`) playback. Safari plays HLS natively; everywhere else needs hls.js, which this
+ * package never imports itself — it is an optional peer you register once, so apps that never
+ * stream do not pay for it:
+ *
+ *   import { setHlsLoader } from '@loidolt/theme-svelte';
+ *   setHlsLoader(() => import('hls.js').then((module) => module.default));
+ */
+let registered = null;
+let cached = null;
+/** Registers how to load hls.js — typically a dynamic import. `null` unregisters. */
+export function setHlsLoader(loader) {
+    registered = loader;
+    cached = null;
+}
+/**
+ * Resolves hls.js through `loader`, else the registered loader, else a global `Hls` from a
+ * script tag. Resolves `null` rather than rejecting when none is available.
+ */
+export function loadHls(loader) {
+    const resolve = (source) => Promise.resolve()
+        .then(source)
+        .then((constructor) => constructor ?? null)
+        .catch(() => null);
+    if (loader)
+        return resolve(loader);
+    cached ??= resolve(registered ?? (() => globalThis.Hls));
+    return cached;
+}
+/** Whether the browser plays HLS without hls.js (Safari, iOS). */
+export function canPlayHlsNatively(media) {
+    const probe = media ?? (typeof document === 'undefined' ? null : document.createElement('video'));
+    if (!probe)
+        return false;
+    return (probe.canPlayType('application/vnd.apple.mpegurl') !== '' ||
+        probe.canPlayType('application/x-mpegURL') !== '');
+}

package/dist/hls.svelte.d.ts

@@ -0,0 +1,22 @@
+import type { Attachment } from 'svelte/attachments';
+import { type HlsLoader } from './hls.js';
+export type HlsStatus = 'idle' | 'loading' | 'native' | 'attached' | 'unsupported' | 'error';
+export interface HlsSourceOptions {
+    /** Loader for this player only. Defaults to the one given to `setHlsLoader()`. */
+    loader?: HlsLoader;
+    /** Passed to the hls.js constructor. */
+    config?: Record<string, unknown>;
+    onError?: (error: Error) => void;
+}
+export interface HlsSource {
+    /** Attach a playlist to a media element: `{@attach hls.source(url)}`. */
+    source(src: string): Attachment<HTMLMediaElement>;
+    readonly status: HlsStatus;
+    readonly error: Error | null;
+}
+/**
+ * Plays an HLS playlist in a media element — natively where the browser can, through hls.js
+ * where it cannot. Fatal network errors retry and media errors attempt recovery before the
+ * status turns to `error`.
+ */
+export declare function createHlsSource(options?: HlsSourceOptions): HlsSource;