nuxt-ui-tools 0.1.0

package/dist/runtime/i18n/provider.vue.d.ts

@@ -0,0 +1,17 @@
+import type { UiToolsLocale, UiToolsMessages } from '#ui-tools/i18n/types';
+type __VLS_Props = {
+    locale?: UiToolsLocale<UiToolsMessages>;
+};
+declare var __VLS_1: {};
+type __VLS_Slots = {} & {
+    default?: (props: typeof __VLS_1) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/runtime/i18n/types.d.ts

@@ -0,0 +1,259 @@
+import type { DeepPartial } from '#ui-tools/shared/types/utils';
+export interface UiToolsTableMessages {
+    header: {
+        refreshData: string;
+        tableView: string;
+        gridView: string;
+    };
+    footer: {
+        rowsSelected: string;
+        rowsPerPage: string;
+        page: string;
+        pageSizeOption: string;
+        previousPage: string;
+        nextPage: string;
+        firstPage: string;
+        lastPage: string;
+    };
+    controls: {
+        addFilter: string;
+        searchFilters: string;
+        noMatchingFilters: string;
+        view: string;
+        searchColumns: string;
+        configurableColumns: string;
+        resetColumns: string;
+        sort: string;
+        loadMore: string;
+    };
+    columnsMenu: {
+        sortAsc: string;
+        sortDesc: string;
+        clearSort: string;
+        pinToLeft: string;
+        pinToRight: string;
+        unpinColumn: string;
+        hideColumn: string;
+    };
+    filters: {
+        panel: {
+            trigger: string;
+            clearAll: string;
+            apply: string;
+        };
+        options: {
+            empty: string;
+        };
+        booleans: {
+            true: string;
+            false: string;
+            empty: string;
+        };
+        preview: {
+            empty: string;
+            selected: string;
+        };
+        operators: {
+            contains: string;
+            is: string;
+            isNot: string;
+            isAnyOf: string;
+            gt: string;
+            gte: string;
+            lt: string;
+            lte: string;
+            before: string;
+            after: string;
+            between: string;
+        };
+    };
+    states: {
+        loaded: string;
+        loadingMore: string;
+        empty: {
+            title: string;
+            description: string;
+        };
+        gridError: {
+            title: string;
+            description: string;
+            action: string;
+        };
+        gridEmpty: {
+            title: string;
+            description: string;
+        };
+    };
+}
+export interface UiToolsSpreadsheetMessages {
+    common: {
+        steps: string;
+        previous: string;
+        continue: string;
+        closeImport: string;
+        preparingReview: string;
+        preparingReviewDescription: string;
+        importRows: string;
+        exportDiscardedRows: string;
+        importSummary: string;
+        clickToChangeHeaderRow: string;
+        referencesStepHint: string;
+        sheetStats: string;
+        arrayValue: string;
+        objectValue: string;
+        arraySummary: string;
+        objectSummary: string;
+    };
+    steps: {
+        upload: {
+            title: string;
+            description: string;
+            stageTitle: string;
+        };
+        structure: {
+            title: string;
+            description: string;
+            stageTitle: string;
+            loadWorkbookFirstTitle: string;
+            loadWorkbookFirstDescription: string;
+            sheetLabel: string;
+            previewTitle: string;
+            autoDetected: string;
+            headerDetectedAtRow: string;
+        };
+        matching: {
+            title: string;
+            description: string;
+            matched: string;
+            needsMatch: string;
+            missing: string;
+            autoMapped: string;
+            ignored: string;
+            ignoreField: string;
+            columnFallback: string;
+            systemField: string;
+            requirement: string;
+            spreadsheetColumn: string;
+            statusHeader: string;
+            required: string;
+            optional: string;
+            searchColumns: string;
+            selectColumn: string;
+            assigned: string;
+            available: string;
+            autoMappedField: string;
+            ignoredColumns: string;
+        };
+        references: {
+            title: string;
+            description: string;
+        };
+        review: {
+            title: string;
+            description: string;
+            importLimit: string;
+            selected: string;
+            discard: string;
+            restore: string;
+            discardRow: string;
+            next: string;
+            prev: string;
+            backToTable: string;
+            restoreRow: string;
+            allRows: string;
+            valid: string;
+            invalid: string;
+            discarded: string;
+            allIssues: string;
+            blocking: string;
+            warnings: string;
+            ready: string;
+            validRows: string;
+            noBlockingIssues: string;
+            willNotBeImported: string;
+            nothingDiscarded: string;
+            row: string;
+            blockingIssues: string;
+            warningsOnly: string;
+            validRow: string;
+            issueBadgeBlocking: string;
+            issueBadgeWarning: string;
+            noValue: string;
+            overflowTitle: string;
+            overflowDescription: string;
+            discardedStatus: string;
+            blockingStatus: string;
+            warningStatus: string;
+            validStatus: string;
+            issueRowsProgress: string;
+            inspectingRow: string;
+            propertyGroups: string;
+            issueGroups: string;
+            rowData: string;
+            issuesOnThisRow: string;
+            byProperty: string;
+            byIssueType: string;
+            ruleKey: string;
+            groupedByIssueType: string;
+            rowLevelIssue: string;
+            affectsFullRow: string;
+            property: string;
+            valueInFile: string;
+            viewAllRowsWithThisIssue: string;
+            autoTrim: string;
+        };
+    };
+    upload: {
+        dropzoneLabel: string;
+        dropzoneDescription: string;
+        parsingFailed: string;
+        downloadTemplate: string;
+        downloadTemplateDescription: string;
+    };
+    validation: {
+        required: string;
+        maxLength: string;
+        minLength: string;
+        number: string;
+        min: string;
+        max: string;
+        between: string;
+        oneOf: string;
+        unrecognizedValue: string;
+        invalidNumberInput: string;
+        invalidBooleanInput: string;
+        missingValue: string;
+        parseFailed: string;
+    };
+}
+export interface UiToolsFormMessages {
+    actions: {
+        nextButton: string;
+        prevButton: string;
+        submitButton: string;
+        cancelButton: string;
+        resetButton: string;
+    };
+    fields: {
+        text: {
+            defaultPlaceholder: string;
+        };
+    };
+}
+export interface Messages {
+    form: UiToolsFormMessages;
+    table: UiToolsTableMessages;
+    spreadsheet: UiToolsSpreadsheetMessages;
+}
+export type Direction = 'ltr' | 'rtl';
+export interface Locale<TMessages = Messages> {
+    name: string;
+    code: string;
+    dir: Direction;
+    messages: TMessages;
+}
+export type UiToolsMessages = Messages;
+export type UiToolsLocaleMessages = Messages;
+export type UiToolsLocaleMessagesPartial = DeepPartial<Messages>;
+export type UiToolsDirection = Direction;
+export type UiToolsLocale<TMessages = Messages> = Locale<TMessages>;

package/dist/runtime/i18n/use-locale.d.ts

@@ -0,0 +1,6 @@
+import { type InjectionKey, type Ref } from 'vue';
+import type { Locale, Messages } from '#ui-tools/i18n/types';
+export declare const uiToolsLocaleContextInjectionKey: InjectionKey<Ref<Locale<Messages> | undefined>>;
+export declare function useUiToolsLocaleRef(localeOverrides?: Ref<Locale<Messages> | undefined>): import("vue").ComputedRef<Locale<Messages>>;
+export declare function useUiToolsLocale(localeOverrides?: Ref<Locale<Messages> | undefined>): import("#ui-tools/i18n/utils").UiToolsLocaleContext<Messages>;
+export declare function provideUiToolsLocale(locale: Ref<Locale<Messages> | undefined>): void;

package/dist/runtime/i18n/use-locale.js

@@ -0,0 +1,37 @@
+import { useLocale as useNuxtUiLocale } from "@nuxt/ui/composables/useLocale";
+import { computed, inject, provide } from "vue";
+import { fr } from "#ui-tools/i18n/locales";
+import en from "#ui-tools/i18n/locales/en";
+import { buildUiToolsLocaleContext } from "#ui-tools/i18n/utils";
+export const uiToolsLocaleContextInjectionKey = Symbol.for("nuxt-ui-tools.locale-context");
+export function useUiToolsLocaleRef(localeOverrides) {
+  const nuxtUiLocale = useNuxtUiLocale();
+  const injectedLocale = inject(uiToolsLocaleContextInjectionKey, void 0);
+  return computed(
+    () => localeOverrides?.value ?? injectedLocale?.value ?? resolveUiToolsLocale({
+      code: nuxtUiLocale.code.value,
+      dir: nuxtUiLocale.dir.value
+    })
+  );
+}
+export function useUiToolsLocale(localeOverrides) {
+  const locale = useUiToolsLocaleRef(localeOverrides);
+  return buildUiToolsLocaleContext(computed(() => locale.value || en));
+}
+export function provideUiToolsLocale(locale) {
+  provide(uiToolsLocaleContextInjectionKey, locale);
+}
+const uiToolsLocales = [en, fr];
+function resolveUiToolsLocale(params) {
+  const normalizedCode = normalizeLocaleCode(params.code);
+  const matchedLocale = uiToolsLocales.find((locale) => normalizeLocaleCode(locale.code) === normalizedCode) ?? uiToolsLocales.find(
+    (locale) => normalizeLocaleCode(locale.code) === normalizedCode.split("_")[0]
+  ) ?? en;
+  return {
+    ...matchedLocale,
+    dir: params.dir ?? matchedLocale.dir
+  };
+}
+function normalizeLocaleCode(value) {
+  return String(value ?? en.code).replace(/-/g, "_").toLowerCase();
+}

package/dist/runtime/i18n/utils.d.ts

@@ -0,0 +1,14 @@
+import { type MaybeRef, type Ref } from 'vue';
+import type { UiToolsDirection, UiToolsLocale } from '#ui-tools/i18n/types';
+export type UiToolsTranslatorOption = Record<string, string | number>;
+export type UiToolsTranslator = (path: string, option?: UiToolsTranslatorOption) => string;
+export interface UiToolsLocaleContext<TMessages> {
+    locale: Ref<UiToolsLocale<TMessages>>;
+    lang: Ref<string>;
+    dir: Ref<UiToolsDirection>;
+    code: Ref<string>;
+    t: UiToolsTranslator;
+}
+export declare function translateUiToolsMessage<TMessages>(path: string, option: UiToolsTranslatorOption | undefined, locale: UiToolsLocale<TMessages>): string;
+export declare function buildUiToolsTranslator<TMessages>(locale: MaybeRef<UiToolsLocale<TMessages>>): UiToolsTranslator;
+export declare function buildUiToolsLocaleContext<TMessages>(locale: MaybeRef<UiToolsLocale<TMessages>>): UiToolsLocaleContext<TMessages>;

package/dist/runtime/i18n/utils.js

@@ -0,0 +1,20 @@
+import { computed, unref } from "vue";
+import { getObjectProperty } from "#ui-tools/shared/utils/object";
+export function translateUiToolsMessage(path, option, locale) {
+  const message = getObjectProperty(locale.messages, path);
+  if (typeof message !== "string") return path;
+  return message.replace(/\{(\w+)\}/g, (_, key) => `${option?.[key] ?? `{${key}}`}`);
+}
+export function buildUiToolsTranslator(locale) {
+  return (path, option) => translateUiToolsMessage(path, option, unref(locale));
+}
+export function buildUiToolsLocaleContext(locale) {
+  const localeRef = computed(() => unref(locale));
+  return {
+    locale: localeRef,
+    lang: computed(() => unref(locale).name),
+    dir: computed(() => unref(locale).dir),
+    code: computed(() => unref(locale).code),
+    t: buildUiToolsTranslator(locale)
+  };
+}

package/dist/runtime/query-state/client.d.ts

@@ -0,0 +1,79 @@
+/**
+ * QueryStateClient — the central coordinator for URL query state.
+ *
+ * Inspired by nuqs's QueryClient:
+ * - Maintains an in-memory cache of parsed query values
+ * - Batches multiple mutations within the same microtask into a single router push/replace
+ * - Supports multiple independent query state consumers without interference
+ * - Pluggable router adapter (vue-router, custom, or manual)
+ */
+import type { Router } from 'vue-router';
+export type HistoryMode = 'push' | 'replace';
+/**
+ * Creates a query-state client bound to a router instance.
+ *
+ * A single client should usually be shared per router so multiple query-state
+ * consumers can coordinate batched writes and route-sync behavior.
+ */
+export interface QueryStateClientOptions {
+    /** Router instance whose current route and navigation methods back this client. */
+    router: Router;
+    /** History mode used when callers do not provide one for a write. */
+    defaultHistoryMode?: HistoryMode;
+}
+type PendingUpdate = {
+    key: string;
+    value: string | null;
+    historyMode: HistoryMode;
+};
+type Subscriber = (key: string, value: string | null) => void;
+export declare class QueryStateClient {
+    private router;
+    private defaultHistoryMode;
+    private cache;
+    private subscribers;
+    private pendingUpdates;
+    private flushScheduled;
+    private _devtoolsListeners;
+    private _mutationLog;
+    /** Create a query-state client backed by the provided router. */
+    constructor(options: QueryStateClientOptions);
+    /** Read a raw query value. Cache-first, falls back to current route. */
+    get(key: string): string | null;
+    /** Read directly from the current route query. */
+    private readFromRoute;
+    /** Queue a single param update. Flushed at the end of the microtask. */
+    set(key: string, value: string | null, historyMode?: HistoryMode): void;
+    /** Queue multiple param updates as a single batch. */
+    setBatch(updates: Array<{
+        key: string;
+        value: string | null;
+    }>, historyMode?: HistoryMode): void;
+    private scheduleFlush;
+    private flush;
+    subscribe(fn: Subscriber): () => void;
+    syncFromRoute(): void;
+    /** Clear the cache and all pending updates. */
+    clear(): void;
+    /** Subscribe to state changes for devtools. Returns unsubscribe fn. */
+    onDevtoolsUpdate(fn: () => void): () => void;
+    private notifyDevtools;
+    /** Snapshot of all internal state for devtools inspection. */
+    __devtools__(): {
+        cache: {
+            [k: string]: string | null;
+        };
+        pendingUpdates: PendingUpdate[];
+        subscriberCount: number;
+        mutationLog: {
+            timestamp: number;
+            key: string;
+            value: string | null;
+            historyMode: HistoryMode;
+        }[];
+        routeQuery: {
+            [x: string]: import("vue-router").LocationQueryValue | import("vue-router").LocationQueryValue[];
+        };
+    };
+}
+export {};

package/dist/runtime/query-state/client.js

@@ -0,0 +1,165 @@
+export class QueryStateClient {
+  router;
+  defaultHistoryMode;
+  cache = /* @__PURE__ */ new Map();
+  subscribers = /* @__PURE__ */ new Set();
+  // Batching
+  pendingUpdates = [];
+  flushScheduled = false;
+  // Devtools
+  _devtoolsListeners = /* @__PURE__ */ new Set();
+  _mutationLog = [];
+  /** Create a query-state client backed by the provided router. */
+  constructor(options) {
+    this.router = options.router;
+    this.defaultHistoryMode = options.defaultHistoryMode ?? "replace";
+  }
+  // ---------------------------------------------------------------------------
+  // Read
+  // ---------------------------------------------------------------------------
+  /** Read a raw query value. Cache-first, falls back to current route. */
+  get(key) {
+    if (this.cache.has(key)) {
+      return this.cache.get(key) ?? null;
+    }
+    const raw = this.readFromRoute(key);
+    this.cache.set(key, raw);
+    return raw;
+  }
+  /** Read directly from the current route query. */
+  readFromRoute(key) {
+    const value = this.router.currentRoute.value.query[key];
+    if (value == null) return null;
+    return Array.isArray(value) ? value[0] : value;
+  }
+  // ---------------------------------------------------------------------------
+  // Write (batched)
+  // ---------------------------------------------------------------------------
+  /** Queue a single param update. Flushed at the end of the microtask. */
+  set(key, value, historyMode) {
+    this.cache.set(key, value);
+    const mode = historyMode ?? this.defaultHistoryMode;
+    this.pendingUpdates.push({ key, value, historyMode: mode });
+    this._mutationLog.push({ timestamp: Date.now(), key, value, historyMode: mode });
+    this.scheduleFlush();
+    for (const subscriber of this.subscribers) {
+      subscriber(key, value);
+    }
+    this.notifyDevtools();
+  }
+  /** Queue multiple param updates as a single batch. */
+  setBatch(updates, historyMode) {
+    const mode = historyMode ?? this.defaultHistoryMode;
+    const now = Date.now();
+    for (const update of updates) {
+      this.cache.set(update.key, update.value);
+      this.pendingUpdates.push({ key: update.key, value: update.value, historyMode: mode });
+      this._mutationLog.push({
+        timestamp: now,
+        key: update.key,
+        value: update.value,
+        historyMode: mode
+      });
+    }
+    this.scheduleFlush();
+    for (const update of updates) {
+      for (const subscriber of this.subscribers) {
+        subscriber(update.key, update.value);
+      }
+    }
+    this.notifyDevtools();
+  }
+  // ---------------------------------------------------------------------------
+  // Flush
+  // ---------------------------------------------------------------------------
+  scheduleFlush() {
+    if (this.flushScheduled) return;
+    this.flushScheduled = true;
+    queueMicrotask(() => this.flush());
+  }
+  flush() {
+    this.flushScheduled = false;
+    if (!this.pendingUpdates.length) return;
+    const updates = this.pendingUpdates;
+    this.pendingUpdates = [];
+    const usePush = updates.some((u) => u.historyMode === "push");
+    const currentQuery = { ...this.router.currentRoute.value.query };
+    const nextQuery = { ...currentQuery };
+    for (const { key, value } of updates) {
+      if (value == null) {
+        delete nextQuery[key];
+      } else {
+        nextQuery[key] = value;
+      }
+    }
+    if (queryEquals(currentQuery, nextQuery)) return;
+    const navigate = usePush ? this.router.push.bind(this.router) : this.router.replace.bind(this.router);
+    navigate({ query: nextQuery });
+  }
+  // ---------------------------------------------------------------------------
+  // Subscribe — for reactive refs to listen to external route changes
+  // ---------------------------------------------------------------------------
+  subscribe(fn) {
+    this.subscribers.add(fn);
+    return () => {
+      this.subscribers.delete(fn);
+    };
+  }
+  // ---------------------------------------------------------------------------
+  // Sync from route — call this on route changes to invalidate stale cache
+  // ---------------------------------------------------------------------------
+  syncFromRoute() {
+    const query = this.router.currentRoute.value.query;
+    for (const [key, cached] of this.cache) {
+      const routeValue = query[key];
+      const rawRoute = routeValue == null ? null : Array.isArray(routeValue) ? routeValue[0] : routeValue;
+      if (rawRoute !== cached) {
+        this.cache.set(key, rawRoute);
+        for (const subscriber of this.subscribers) {
+          subscriber(key, rawRoute);
+        }
+      }
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Reset
+  // ---------------------------------------------------------------------------
+  /** Clear the cache and all pending updates. */
+  clear() {
+    this.cache.clear();
+    this.pendingUpdates = [];
+  }
+  // ---------------------------------------------------------------------------
+  // Devtools
+  // ---------------------------------------------------------------------------
+  /** Subscribe to state changes for devtools. Returns unsubscribe fn. */
+  onDevtoolsUpdate(fn) {
+    this._devtoolsListeners.add(fn);
+    return () => {
+      this._devtoolsListeners.delete(fn);
+    };
+  }
+  notifyDevtools() {
+    for (const fn of this._devtoolsListeners) fn();
+  }
+  /** Snapshot of all internal state for devtools inspection. */
+  __devtools__() {
+    return {
+      cache: Object.fromEntries(this.cache),
+      pendingUpdates: [...this.pendingUpdates],
+      subscriberCount: this.subscribers.size,
+      mutationLog: this._mutationLog.slice(-50),
+      // keep last 50
+      routeQuery: { ...this.router.currentRoute.value.query }
+    };
+  }
+}
+function queryEquals(a, b) {
+  const aKeys = Object.keys(a);
+  const bKeys = Object.keys(b);
+  if (aKeys.length !== bKeys.length) return false;
+  for (const key of aKeys) {
+    if (a[key] !== b[key]) return false;
+  }
+  return true;
+}

package/dist/runtime/query-state/codecs.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Serializes and parses a single query-string value.
+ *
+ * Query-state composables always store raw URL values as strings. A codec is
+ * the boundary that turns those strings into typed values for the app and back
+ * into URL-safe strings when writing.
+ */
+export interface QueryCodec<T> {
+    /** Parse a raw query-string value into the typed runtime value. */
+    parse: (raw: string) => T;
+    /**
+     * Serialize a typed value for the URL.
+     *
+     * Return `null` when the value should be omitted from the query string.
+     */
+    serialize: (value: T) => string | null;
+}
+export declare const stringCodec: QueryCodec<string>;
+export declare const numberCodec: QueryCodec<number>;
+export declare const booleanCodec: QueryCodec<boolean>;
+export declare const dateISOCodec: QueryCodec<Date>;
+/**
+ * Creates a codec that only accepts values from a fixed string union.
+ *
+ * Invalid incoming query values parse to `undefined`, which lets
+ * `useQueryState(...)` and `useQueryStates(...)` fall back to their defaults.
+ *
+ * @example
+ * ```ts
+ * const layoutCodec = createEnumCodec(['grid', 'table'])
+ * ```
+ */
+export declare function createEnumCodec<const T extends readonly string[]>(values: T): QueryCodec<T[number] | undefined>;
+/**
+ * Creates a codec for separator-delimited lists, such as `"a,b,c"`.
+ *
+ * Empty input parses to an empty array and empty arrays serialize to `null`, so
+ * default query-state behavior removes the key from the URL.
+ *
+ * @example
+ * ```ts
+ * const tagsCodec = createArrayCodec(stringCodec)
+ * ```
+ */
+export declare function createArrayCodec<T>(itemCodec: QueryCodec<T>, separator?: string): QueryCodec<T[]>;

package/dist/runtime/query-state/codecs.js

@@ -0,0 +1,41 @@
+export const stringCodec = {
+  parse: (raw) => raw,
+  serialize: (value) => value
+};
+export const numberCodec = {
+  parse: (raw) => Number(raw),
+  serialize: (value) => String(value)
+};
+export const booleanCodec = {
+  parse: (raw) => raw === "true",
+  serialize: (value) => value ? "true" : "false"
+};
+export const dateISOCodec = {
+  parse: (raw) => new Date(raw),
+  serialize: (value) => value.toISOString()
+};
+export function createEnumCodec(values) {
+  const set = new Set(values);
+  return {
+    parse(raw) {
+      if (set.has(raw)) return raw;
+      return void 0;
+    },
+    serialize(value) {
+      if (value != null && set.has(value)) return value;
+      return null;
+    }
+  };
+}
+export function createArrayCodec(itemCodec, separator = ",") {
+  return {
+    parse(raw) {
+      if (!raw) return [];
+      return raw.split(separator).map((part) => itemCodec.parse(part));
+    },
+    serialize(value) {
+      if (!value.length) return null;
+      return value.map((item) => itemCodec.serialize(item)).filter(Boolean).join(separator);
+    }
+  };
+}