@jk2908/solas 0.5.3 → 0.6.0

package/dist/internal/browser-router/shared.d.ts

@@ -1,170 +1,189 @@
-import { Solas } from '../../solas.js';
-export declare namespace BrowserRouter {
-    export type Params = Record<string, string>;
-    export type Query = Record<string, string | number | boolean>;
-    export type Path = keyof Solas.Routes & string;
-    type Replace = {
-        replace?: boolean;
+import * as Solas from '../../solas.js';
+export type Params = Record<string, string>;
+export type Query = Record<string, string | number | boolean>;
+export type Path = keyof Solas.Routes & string;
+type Replace = {
+    replace?: boolean;
+};
+export type GoOptions = {
+    replace?: boolean;
+    query?: Query;
+    params?: Params;
+};
+export type Context = {
+    go: Go;
+    prefetch: (path: string) => void;
+    refresh: Refresh;
+    isNavigating: boolean;
+    url: {
+        pathname: string;
+        search?: string;
+        hash?: string;
     };
-    export type GoOptions = {
-        replace?: boolean;
-        query?: Query;
-        params?: Params;
+    history: {
+        entries: HistoryEntry[];
+        index: number;
     };
-    /**
-     * These targets are used as-is. They are not matched against the route table,
-     * so this covers normal external URLs and hash-only links
-     */
-    export type ExternalTarget = `${string}:${string}` | `//${string}` | `#${string}`;
-    export function isHashOnlyTarget(target: string): boolean;
-    export function isExternalTarget(target: string, origin: string): boolean;
-    /**
-     * Turn a route pattern into the real path shape a caller can use. In practice,
-     * every ':param' or '*' part becomes a plain string slot
-     *
-     * @example
-     * ```ts
-     * // '/p/:id' becomes '/p/${string}'
-     * // '/test/*' becomes '/test/${string}'
-     * // '/posts' stays '/posts'
-     * ```
-     *
-     * @example
-     * ```ts
-     * type A = ResolvedPath<'/posts/:id'>
-     * // '/posts/${string}'
-     * ```
-     *
-     * @example
-     * ```ts
-     * type B = ResolvedPath<'/docs/*'>
-     * // '/docs/${string}'
-     * ```
-     */
-    export type ResolvedPath<TPath extends string> = TPath extends `${infer Start}:${string}/${infer Rest}` ? `${Start}${string}/${ResolvedPath<Rest>}` : TPath extends `${infer Start}:${string}` ? `${Start}${string}` : TPath extends `${infer Start}*${infer Rest}` ? `${Start}${string}${ResolvedPath<Rest>}` : TPath;
-    /**
-     * Once we have a real path, also allow the usual query-string and hash forms
-     *
-     * @example
-     * ```ts
-     * type A = TargetSuffix<'/posts/123'>
-     * // '/posts/123' | '/posts/123?${string}' | '/posts/123#${string}' | '/posts/123?${string}#${string}'
-     * ```
-     */
-    export type TargetSuffix<TPath extends string> = TPath | `${TPath}?${string}` | `${TPath}#${string}` | `${TPath}?${string}#${string}`;
-    /**
-     * This is the final string form a caller can navigate to. It can be an external
-     * URL, or a concrete URL that matches one of the  known routes
-     *
-     * @example
-     * ```ts
-     * type A = Target
-     * // 'https://example.com'
-     * // '#intro'
-     * // '/posts/123'
-     * // '/posts/123?draft=true'
-     * ```
-     */
-    export type Target = ExternalTarget | TargetSuffix<ResolvedPath<Path>>;
-    /**
-     * Extra options for callers who already have a finished target string
-     *
-     * @example
-     * ```ts
-     * const a: TargetConfig = { query: { page: 2 } }
-     * // params is rejected here because the path is already complete
-     * ```
-     */
-    type TargetConfig = {
-        params?: never;
-        query?: Query;
-    };
-    /**
-     * Extra options for callers who pass a route pattern and params separately.
-     * If the route definition says that route needs params, this type makes
-     * those params required. If the route has no params, it rejects them
-     *
-     * @example
-     * ```ts
-     * // if Solas.Routes['/posts/:id'] is { params: { id: string } }
-     * type A = PatternConfig<'/posts/:id'>
-     * // { query?: Query } & { params: { id: string } }
-     * ```
-     *
-     * @example
-     * ```ts
-     * // if Solas.Routes['/about'] has no params field
-     * type B = PatternConfig<'/about'>
-     * // { query?: Query } & { params?: never }
-     * ```
-     */
-    type PatternConfig<TPath extends Path> = {
-        query?: Query;
-    } & (Solas.Routes[TPath] extends {
-        params: infer TParams extends Params;
-    } ? {
-        params: TParams;
-    } : {
-        params?: never;
-    });
-    /**
-     * Typed <Link /> props, using `href` instead of the internal `to` name
-     *
-     * `query` is always allowed
-     * `params` are only allowed when `href` is a known route pattern
-     *
-     * @example
-     * ```ts
-     * const a: LinkProps = { href: '/posts/:id', params: { id: '123' } }
-     * const b: LinkProps = { href: '/posts/123?draft=true' }
-     * ```
-     */
-    export type LinkProps = ({
-        href: Target;
-    } & TargetConfig) | (keyof Solas.Routes extends never ? never : {
-        [TPath in Path]: {
-            href: TPath;
-        } & PatternConfig<TPath>;
-    }[Path]);
-    /**
-     * Typed input for router.go(), using the same route rules as <Link />
-     *
-     * @example
-     * ```ts
-     * go('/p/post-2')
-     * go('/?foo=bar', { replace: true })
-     * ```
-     *
-     * @example
-     * ```ts
-     * go('/p/:id', { params: { id: 'post-2' }, replace: true })
-     * ```
-     *
-     * The last overload is the fallback for plain `string` values. The
-     * `string extends TTo` check stops that fallback from taking over
-     * when TypeScript already knows the caller passed a more specific
-     * string literal
-     *
-     * @example
-     * ```ts
-     * declare const dynamicPath: string
-     * go(dynamicPath, { replace: true })
-     * ```
-     */
-    export type Go = {
-        <TTo extends Path>(to: TTo, opts?: PatternConfig<TTo> & Replace): Promise<string>;
-        <TTo extends Target>(to: TTo, opts?: TargetConfig & Replace): Promise<string>;
-        <TTo extends string>(to: string extends TTo ? TTo : never, opts?: GoOptions): Promise<string>;
-    };
-    export type Refresh = () => Promise<string>;
-    /**
-     * Convert a route pattern and params into a real path string. This is used internally
-     * to implement <Link /> and router.go
-     */
-    export function toTarget(path: string, params?: Record<string, string>, query?: Query): string;
-    export {};
-}
+};
+export type HistoryEntry = {
+    pathname: string;
+    search: string;
+    hash: string;
+};
+/**
+ * These targets are used as-is. They are not matched against the route table,
+ * so this covers normal external URLs and hash-only links
+ */
+export type ExternalTarget = `${string}:${string}` | `//${string}` | `#${string}`;
+export declare function isHashOnlyTarget(target: string): boolean;
+export declare function isExternalTarget(target: string, origin: string): boolean;
+/**
+ * Turn a route pattern into the real path shape a caller can use. In practice,
+ * every ':param' or '*' part becomes a plain string slot
+ *
+ * @example
+ * ```ts
+ * // '/p/:id' becomes '/p/${string}'
+ * // '/test/*' becomes '/test/${string}'
+ * // '/posts' stays '/posts'
+ * ```
+ *
+ * @example
+ * ```ts
+ * type A = ResolvedPath<'/posts/:id'>
+ * // '/posts/${string}'
+ * ```
+ *
+ * @example
+ * ```ts
+ * type B = ResolvedPath<'/docs/*'>
+ * // '/docs/${string}'
+ * ```
+ */
+export type ResolvedPath<TPath extends string> = TPath extends `${infer Start}:${string}/${infer Rest}` ? `${Start}${string}/${ResolvedPath<Rest>}` : TPath extends `${infer Start}:${string}` ? `${Start}${string}` : TPath extends `${infer Start}*${infer Rest}` ? `${Start}${string}${ResolvedPath<Rest>}` : TPath;
+/**
+ * Once we have a real path, also allow the usual query-string and hash forms
+ *
+ * @example
+ * ```ts
+ * type A = TargetSuffix<'/posts/123'>
+ * // '/posts/123' | '/posts/123?${string}' | '/posts/123#${string}' | '/posts/123?${string}#${string}'
+ * ```
+ */
+export type TargetSuffix<TPath extends string> = TPath | `${TPath}?${string}` | `${TPath}#${string}` | `${TPath}?${string}#${string}`;
+/**
+ * This is the final string form a caller can navigate to. It can be an external
+ * URL, or a concrete URL that matches one of the  known routes
+ *
+ * @example
+ * ```ts
+ * type A = Target
+ * // 'https://example.com'
+ * // '#intro'
+ * // '/posts/123'
+ * // '/posts/123?draft=true'
+ * ```
+ */
+export type Target = ExternalTarget | TargetSuffix<ResolvedPath<Path>>;
+/**
+ * Extra options for callers who already have a finished target string
+ *
+ * @example
+ * ```ts
+ * const a: TargetConfig = { query: { page: 2 } }
+ * // params is rejected here because the path is already complete
+ * ```
+ */
+type TargetConfig = {
+    params?: never;
+    query?: Query;
+};
+/**
+ * Extra options for callers who pass a route pattern and params separately.
+ * If the route definition says that route needs params, this type makes
+ * those params required. If the route has no params, it rejects them
+ *
+ * @example
+ * ```ts
+ * // if Solas.Routes['/posts/:id'] is { params: { id: string } }
+ * type A = PatternConfig<'/posts/:id'>
+ * // { query?: Query } & { params: { id: string } }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // if Solas.Routes['/about'] has no params field
+ * type B = PatternConfig<'/about'>
+ * // { query?: Query } & { params?: never }
+ * ```
+ */
+type PatternConfig<TPath extends Path> = {
+    query?: Query;
+} & (Solas.Routes[TPath] extends {
+    params: infer TParams extends Params;
+} ? {
+    params: TParams;
+} : {
+    params?: never;
+});
+/**
+ * Typed <Link /> props, using `href` instead of the internal `to` name
+ *
+ * `query` is always allowed
+ * `params` are only allowed when `href` is a known route pattern
+ *
+ * @example
+ * ```ts
+ * const a: LinkProps = { href: '/posts/:id', params: { id: '123' } }
+ * const b: LinkProps = { href: '/posts/123?draft=true' }
+ * ```
+ */
+export type LinkProps = ({
+    href: Target;
+} & TargetConfig) | (keyof Solas.Routes extends never ? never : {
+    [TPath in Path]: {
+        href: TPath;
+    } & PatternConfig<TPath>;
+}[Path]);
+/**
+ * Typed input for router.go(), using the same route rules as <Link />
+ *
+ * @example
+ * ```ts
+ * go('/p/post-2')
+ * go('/?foo=bar', { replace: true })
+ * ```
+ *
+ * @example
+ * ```ts
+ * go('/p/:id', { params: { id: 'post-2' }, replace: true })
+ * ```
+ *
+ * The last overload is the fallback for plain `string` values. The
+ * `string extends TTo` check stops that fallback from taking over
+ * when TypeScript already knows the caller passed a more specific
+ * string literal
+ *
+ * @example
+ * ```ts
+ * declare const dynamicPath: string
+ * go(dynamicPath, { replace: true })
+ * ```
+ */
+export type Go = {
+    (to: number): Promise<string>;
+    <TTo extends Path>(to: TTo, opts?: PatternConfig<TTo> & Replace): Promise<string>;
+    <TTo extends Target>(to: TTo, opts?: TargetConfig & Replace): Promise<string>;
+    <TTo extends string>(to: string extends TTo ? TTo : never, opts?: GoOptions): Promise<string>;
+};
+export type Refresh = () => Promise<string>;
+/**
+ * Convert a route pattern and params into a real path string. This is used internally
+ * to implement <Link /> and router.go
+ */
+export declare function toTarget(path: string, params?: Record<string, string>, query?: Query): string;
 /**
  * Apply the base path to a target string when needed
  */
 export declare function withBase(target: string): string;
+export {};

package/dist/internal/browser-router/shared.js

@@ -1,72 +1,65 @@
-import { BasePath } from '../../utils/base-path.js';
-const BASE_PATH = BasePath.normalise(import.meta.env.BASE_URL);
-export { BrowserRouter };
-var BrowserRouter;
-(function (BrowserRouter) {
-    function isHashOnlyTarget(target) {
-        return target.startsWith('#');
+import { applyBasePath, normaliseBasePath } from '../../utils/base-path.js';
+const BASE_PATH = normaliseBasePath(import.meta.env.BASE_URL);
+export function isHashOnlyTarget(target) {
+    return target.startsWith('#');
+}
+export function isExternalTarget(target, origin) {
+    if (isHashOnlyTarget(target))
+        return false;
+    try {
+        return new URL(target, origin).origin !== origin;
     }
-    BrowserRouter.isHashOnlyTarget = isHashOnlyTarget;
-    function isExternalTarget(target, origin) {
-        if (isHashOnlyTarget(target))
-            return false;
-        try {
-            return new URL(target, origin).origin !== origin;
-        }
-        catch {
-            return false;
-        }
+    catch {
+        return false;
     }
-    BrowserRouter.isExternalTarget = isExternalTarget;
-    /**
-     * Convert a route pattern and params into a real path string. This is used internally
-     * to implement <Link /> and router.go
-     */
-    function toTarget(path, params, query) {
-        const used = new Set();
-        // first, replace all the :param parts with the corresponding params
-        let to = path.replaceAll(/:([A-Za-z0-9_]+)/g, (_, key) => {
-            const value = params?.[key];
-            if (value == null) {
-                throw new Error(`[Link]: missing route param: ${key}`);
-            }
-            used.add(key);
-            return encodeURIComponent(value);
-        });
-        if (to.includes('*')) {
-            const remaining = Object.entries(params ?? {}).filter(([key]) => !used.has(key));
-            if (remaining.length !== 1) {
-                throw new Error('[Link]: wildcard routes require exactly one unmatched param');
-            }
-            to = to.replace('*', remaining[0][1].split('/').map(encodeURIComponent).join('/'));
+}
+/**
+ * Convert a route pattern and params into a real path string. This is used internally
+ * to implement <Link /> and router.go
+ */
+export function toTarget(path, params, query) {
+    const used = new Set();
+    // first, replace all the :param parts with the corresponding params
+    let to = path.replaceAll(/:([A-Za-z0-9_]+)/g, (_, key) => {
+        const value = params?.[key];
+        if (value == null) {
+            throw new Error(`[Link]: missing route param: ${key}`);
         }
-        if (!query)
-            return withBase(to);
-        const hashIndex = to.indexOf('#');
-        const hash = hashIndex >= 0 ? to.slice(hashIndex) : '';
-        const pathWithSearch = hashIndex >= 0 ? to.slice(0, hashIndex) : to;
-        const searchIndex = pathWithSearch.indexOf('?');
-        const pathname = searchIndex >= 0 ? pathWithSearch.slice(0, searchIndex) : pathWithSearch;
-        const currentSearch = searchIndex >= 0 ? pathWithSearch.slice(searchIndex + 1) : '';
-        const search = new URLSearchParams(currentSearch);
-        for (const [key, value] of Object.entries(query)) {
-            search.set(key, String(value));
+        used.add(key);
+        return encodeURIComponent(value);
+    });
+    if (to.includes('*')) {
+        const remaining = Object.entries(params ?? {}).filter(([key]) => !used.has(key));
+        if (remaining.length !== 1) {
+            throw new Error('[Link]: wildcard routes require exactly one unmatched param');
         }
-        const value = search.toString();
-        return withBase(`${pathname}${value.length > 0 ? `?${value}` : ''}${hash}`);
+        to = to.replace('*', remaining[0][1].split('/').map(encodeURIComponent).join('/'));
     }
-    BrowserRouter.toTarget = toTarget;
-})(BrowserRouter || (BrowserRouter = {}));
+    if (!query)
+        return withBase(to);
+    const hashIndex = to.indexOf('#');
+    const hash = hashIndex >= 0 ? to.slice(hashIndex) : '';
+    const pathWithSearch = hashIndex >= 0 ? to.slice(0, hashIndex) : to;
+    const searchIndex = pathWithSearch.indexOf('?');
+    const pathname = searchIndex >= 0 ? pathWithSearch.slice(0, searchIndex) : pathWithSearch;
+    const currentSearch = searchIndex >= 0 ? pathWithSearch.slice(searchIndex + 1) : '';
+    const search = new URLSearchParams(currentSearch);
+    for (const [key, value] of Object.entries(query)) {
+        search.set(key, String(value));
+    }
+    const value = search.toString();
+    return withBase(`${pathname}${value.length > 0 ? `?${value}` : ''}${hash}`);
+}
 /**
  * Apply the base path to a target string when needed
  */
 export function withBase(target) {
-    if (BrowserRouter.isHashOnlyTarget(target))
+    if (isHashOnlyTarget(target))
         return target;
     if (target.startsWith('//') || /^[A-Za-z][A-Za-z\d+.-]*:/.test(target))
         return target;
     const suffixIndex = target.search(/[?#]/);
     const pathname = suffixIndex === -1 ? target : target.slice(0, suffixIndex);
     const suffix = suffixIndex === -1 ? '' : target.slice(suffixIndex);
-    return `${BasePath.apply(pathname || '/', BASE_PATH)}${suffix}`;
+    return `${applyBasePath(pathname || '/', BASE_PATH)}${suffix}`;
 }

package/dist/internal/browser-router/use-router.d.ts

@@ -1,10 +1 @@
-export declare function useRouter(): {
-    go: import("./shared.js").BrowserRouter.Go;
-    prefetch: (path: string) => void;
-    refresh: import("./shared.js").BrowserRouter.Refresh;
-    isNavigating: boolean;
-    url: {
-        pathname?: string | undefined;
-        search?: string | undefined;
-    };
-};
+export declare function useRouter(): import("./shared.js").Context;

package/dist/internal/browser-router/use-search-params.js

@@ -1,14 +1,14 @@
 import { useMemo, useSyncExternalStore } from 'react';
-import { Solas } from '../../solas.js';
+import * as Events from '../../events.js';
 import { useRouter } from '../browser-router/use-router.js';
 export function useSearchParams() {
     const { url } = useRouter();
     const search = useSyncExternalStore(fn => {
         window.addEventListener('popstate', fn);
-        window.addEventListener(Solas.Events.names.NAVIGATION, fn);
+        window.addEventListener(Events.names.NAVIGATION, fn);
         return () => {
             window.removeEventListener('popstate', fn);
-            window.removeEventListener(Solas.Events.names.NAVIGATION, fn);
+            window.removeEventListener(Events.names.NAVIGATION, fn);
         };
     }, () => window.location.search, () => url?.search);
     return useMemo(() => new URLSearchParams(search), [search]);