@vamos-ui/react 0.0.0-stage → 0.3.0

package/dist/lib/message-format.js

@@ -0,0 +1,116 @@
+/**
+ * ICU-lite message formatting — React-free, ~no dependencies.
+ *
+ * Supported syntax:
+ * - `{name}` — replaced with `vars.name` (numbers are formatted with the locale: 1250 → "1,250").
+ * - `{count, plural, =0 {No files} one {# file} other {# files}}` — `Intl.PluralRules`; `#` is the formatted number.
+ * - `{count, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}`.
+ * - `{role, select, admin {Administrator} other {Member}}`.
+ *
+ * Unknown placeholders are left as-is (`{name}`), so a missing variable is visible, not silent.
+ */
+const pluralCache = new Map();
+const numberCache = new Map();
+function pluralRules(locale, type) {
+    const k = locale + type;
+    let r = pluralCache.get(k);
+    if (!r)
+        pluralCache.set(k, (r = new Intl.PluralRules(locale, { type })));
+    return r;
+}
+function numberFormat(locale) {
+    let f = numberCache.get(locale);
+    if (!f)
+        numberCache.set(locale, (f = new Intl.NumberFormat(locale)));
+    return f;
+}
+/** Index of the `}` closing the `{` at `open`, or -1. */
+function closing(s, open) {
+    let depth = 0;
+    for (let i = open; i < s.length; i++) {
+        if (s[i] === "{")
+            depth++;
+        else if (s[i] === "}" && --depth === 0)
+            return i;
+    }
+    return -1;
+}
+function parseBranches(s) {
+    const out = new Map();
+    let i = 0;
+    while (i < s.length) {
+        while (i < s.length && /\s/.test(s[i]))
+            i++;
+        const start = i;
+        while (i < s.length && s[i] !== "{" && !/\s/.test(s[i]))
+            i++;
+        const key = s.slice(start, i);
+        while (i < s.length && /\s/.test(s[i]))
+            i++;
+        if (s[i] !== "{")
+            break;
+        const end = closing(s, i);
+        if (end === -1)
+            break;
+        if (key)
+            out.set(key, s.slice(i + 1, end));
+        i = end + 1;
+    }
+    return out;
+}
+/**
+ * Formats a message template.
+ *
+ * ```ts
+ * formatMessage("Remove {label}", { label: "Design" }); // "Remove Design"
+ * formatMessage("{count, plural, one {# reply} other {# replies}}", { count: 1250 }, "en-US"); // "1,250 replies"
+ * ```
+ */
+export function formatMessage(template, vars = {}, locale = "en-US") {
+    if (!template.includes("{"))
+        return template;
+    let out = "";
+    let i = 0;
+    while (i < template.length) {
+        const open = template.indexOf("{", i);
+        if (open === -1) {
+            out += template.slice(i);
+            break;
+        }
+        out += template.slice(i, open);
+        const close = closing(template, open);
+        if (close === -1) {
+            out += template.slice(open);
+            break;
+        }
+        const inner = template.slice(open + 1, close);
+        const m = /^\s*([\w.-]+)\s*(?:,\s*(plural|selectordinal|select)\s*,([\s\S]*))?$/.exec(inner);
+        if (!m)
+            out += `{${inner}}`;
+        else {
+            const [, name, kind, rest] = m;
+            const value = vars[name];
+            if (!kind) {
+                out += value === undefined || value === null ? `{${name}}` : typeof value === "number" ? numberFormat(locale).format(value) : String(value);
+            }
+            else {
+                const branches = parseBranches(rest ?? "");
+                let branch;
+                if (kind === "select")
+                    branch = branches.get(String(value)) ?? branches.get("other");
+                else {
+                    const n = Number(value);
+                    branch =
+                        branches.get(`=${n}`) ??
+                            branches.get(pluralRules(locale, kind === "plural" ? "cardinal" : "ordinal").select(n)) ??
+                            branches.get("other");
+                    if (branch !== undefined)
+                        branch = branch.replace(/#/g, Number.isFinite(n) ? numberFormat(locale).format(n) : String(value));
+                }
+                out += branch === undefined ? "" : formatMessage(branch, vars, locale);
+            }
+        }
+        i = close + 1;
+    }
+    return out;
+}

package/dist/lib/nav.d.ts

@@ -0,0 +1,132 @@
+import type * as React from "react";
+/**
+ * The navigation model shared by Sidebar, App shell, Breadcrumb ("auto"), Page header and the
+ * Command palette's "Go to" commands. Pure data + pure helpers (no React), so it works on the
+ * server and is unit-tested on its own.
+ */
+/** A count, a short label, or a styled badge. Live values go through `SidebarNav badges`, not the config. */
+export type BadgeSpec = number | string | {
+    count?: number;
+    /** Default `"accent"`. */
+    tone?: "accent" | "danger" | "warning" | "neutral";
+    /** Only a dot (e.g. "something new"). */
+    dot?: boolean;
+    /** Accessible text, e.g. "4 pending". Default from the dictionary (`sidebar.badge`). */
+    label?: string;
+};
+export type NavIcon = React.ComponentType<{
+    className?: string;
+    strokeWidth?: number;
+    "aria-hidden"?: boolean | "true" | "false";
+}>;
+export interface NavItem {
+    /** Stable key for badges, commands, analytics and the active trail. */
+    id: string;
+    label: string;
+    /** Omitted → a section parent that only opens its children. */
+    href?: string;
+    icon?: NavIcon;
+    /** Up to 3 levels. */
+    children?: NavItem[];
+    /** Extra active patterns (`"/posts/*"` = any child path) or a predicate. */
+    match?: string[] | ((path: string) => boolean);
+    /** Hidden unless `can(permission)` (all of them for an array). UI only — enforce on the server. */
+    permission?: string | string[];
+    /** Hidden unless `features[feature]` is true (module toggle / feature flag). */
+    feature?: string;
+    /** Opens in a new tab with an ↗ icon. Default: detected from an absolute `href`. */
+    external?: boolean;
+    /** Extra search terms for ⌘K "Go to". */
+    keywords?: string[];
+    /** Static badge. */
+    badge?: BadgeSpec;
+    /** `true`, or a reason shown as a badge ("Coming soon"). */
+    disabled?: boolean | string;
+}
+export interface NavGroup {
+    type: "group";
+    id: string;
+    /** Section heading. */
+    label?: string;
+    items: NavItem[];
+}
+export interface NavSeparator {
+    type: "separator";
+    id?: string;
+}
+/** One entry of a nav config: an item, a labelled group (section) or a separator. */
+export type NavNode = NavItem | NavGroup | NavSeparator;
+/** Alias of `NavNode`. */
+export type NavEntry = NavNode;
+export declare const isNavGroup: (n: NavNode) => n is NavGroup;
+export declare const isNavSeparator: (n: NavNode) => n is NavSeparator;
+export declare const isNavItem: (n: NavNode) => n is NavItem;
+export interface FilterNavOptions {
+    can?: (permission: string) => boolean;
+    features?: Record<string, boolean | undefined>;
+}
+/**
+ * Drops items the user can't see (`permission` via `can`, `feature` via `features`), then empty
+ * groups and leading / trailing / doubled separators. **UI only** — permissions must be enforced
+ * on the server.
+ */
+export declare function filterNav(nodes: NavNode[], options?: FilterNavOptions): NavNode[];
+/** Top-level items of a config, with groups unwrapped. */
+export declare function navItems(nodes: NavNode[]): NavItem[];
+/** `true` for `http(s)://`, protocol-relative and `mailto:`-style hrefs. */
+export declare const isAbsoluteHref: (href: string) => boolean;
+/**
+ * Length of the match of `pattern` against `path`, or -1. `/` matches only exactly; `"/posts"`
+ * matches `/posts` and `/posts/12`; `"/posts/*"` matches only children.
+ */
+export declare function matchPath(pattern: string, path: string): number;
+export interface ActiveNav {
+    /** Ids from the top-level item down to the active leaf, e.g. `["posts", "posts.categories"]`. */
+    trail: string[];
+    leafId?: string;
+}
+/**
+ * The active item by **longest-prefix match** over every `href` and `match` pattern, so the
+ * dashboard (`/site`) isn't active on `/site/posts`. The trail feeds Sidebar, Breadcrumb and Page header.
+ */
+export declare function resolveActive(nodes: NavNode[], path: string | undefined): ActiveNav;
+export interface FlatNavItem {
+    id: string;
+    label: string;
+    href: string;
+    /** Labels from the top level down, e.g. `["Settings", "Reading"]`. */
+    trail: string[];
+    /** Ids from the top level down. */
+    ids: string[];
+    /** Heading of the group the item sits in. */
+    group?: string;
+    icon?: NavIcon;
+    keywords?: string[];
+    external?: boolean;
+}
+/**
+ * Every navigable item (has an `href`, not disabled) as a flat list — for ⌘K "Go to" and Breadcrumb.
+ * A child whose `href` equals its parent's (an "All posts" index) is folded into the parent.
+ */
+export declare function flattenNav(nodes: NavNode[]): FlatNavItem[];
+/** Finds an item by id anywhere in the tree. */
+export declare function findNavItem(nodes: NavNode[], id: string): NavItem | undefined;
+/** Breadcrumb items for an active trail (`resolveActive(...).trail`). */
+export declare function navTrailItems(nodes: NavNode[], trail: string[]): Array<{
+    id: string;
+    label: string;
+    href?: string;
+}>;
+export interface NormalisedBadge {
+    count?: number;
+    text?: string;
+    tone: "accent" | "danger" | "warning" | "neutral";
+    dot: boolean;
+    label?: string;
+}
+/** Normalises a `BadgeSpec`; `undefined` / `0` / empty → `undefined` (nothing to show). */
+export declare function normaliseBadge(b: BadgeSpec | undefined | null): NormalisedBadge | undefined;
+/** Cookie the App shell stores the collapsed state in (`"1"` = rail). Read it on the server to avoid a flash. */
+export declare const SIDEBAR_COOKIE = "ui-sidebar";
+/** `true` / `false` from a `ui-sidebar` cookie value (or a whole `Cookie` header); `undefined` when unset. */
+export declare function parseSidebarCookie(value: string | null | undefined): boolean | undefined;

package/dist/lib/nav.js

@@ -0,0 +1,178 @@
+export const isNavGroup = (n) => n.type === "group";
+export const isNavSeparator = (n) => n.type === "separator";
+export const isNavItem = (n) => !("type" in n) || n.type === undefined;
+function allowed(item, { can, features }) {
+    if (item.permission && can) {
+        const list = Array.isArray(item.permission) ? item.permission : [item.permission];
+        if (!list.every((p) => can(p)))
+            return false;
+    }
+    if (item.feature && features && !features[item.feature])
+        return false;
+    return true;
+}
+function filterItems(items, o) {
+    const out = [];
+    for (const it of items) {
+        if (!allowed(it, o))
+            continue;
+        if (it.children) {
+            const children = filterItems(it.children, o);
+            // A parent with no href and no visible child has nothing to open.
+            if (!it.href && children.length === 0)
+                continue;
+            out.push({ ...it, children: children.length ? children : undefined });
+        }
+        else
+            out.push(it);
+    }
+    return out;
+}
+/**
+ * Drops items the user can't see (`permission` via `can`, `feature` via `features`), then empty
+ * groups and leading / trailing / doubled separators. **UI only** — permissions must be enforced
+ * on the server.
+ */
+export function filterNav(nodes, options = {}) {
+    const out = [];
+    for (const n of nodes) {
+        if (isNavSeparator(n)) {
+            if (out.length && !isNavSeparator(out[out.length - 1]))
+                out.push(n);
+            continue;
+        }
+        if (isNavGroup(n)) {
+            const items = filterItems(n.items, options);
+            if (items.length)
+                out.push({ ...n, items });
+            continue;
+        }
+        const [it] = filterItems([n], options);
+        if (it)
+            out.push(it);
+    }
+    while (out.length && isNavSeparator(out[out.length - 1]))
+        out.pop();
+    return out;
+}
+/** Top-level items of a config, with groups unwrapped. */
+export function navItems(nodes) {
+    return nodes.flatMap((n) => (isNavGroup(n) ? n.items : isNavItem(n) ? [n] : []));
+}
+const clean = (p) => {
+    const path = p.split(/[?#]/)[0] || "/";
+    return path.length > 1 ? path.replace(/\/+$/, "") : path;
+};
+/** `true` for `http(s)://`, protocol-relative and `mailto:`-style hrefs. */
+export const isAbsoluteHref = (href) => /^([a-z][a-z\d+.-]*:|\/\/)/i.test(href);
+/**
+ * Length of the match of `pattern` against `path`, or -1. `/` matches only exactly; `"/posts"`
+ * matches `/posts` and `/posts/12`; `"/posts/*"` matches only children.
+ */
+export function matchPath(pattern, path) {
+    if (isAbsoluteHref(pattern))
+        return -1;
+    const p = clean(path);
+    if (pattern.endsWith("/*")) {
+        const base = clean(pattern.slice(0, -2));
+        return p.startsWith(base === "/" ? "/" : `${base}/`) && p !== base ? base.length + 1 : -1;
+    }
+    const t = clean(pattern);
+    if (t === "/")
+        return p === "/" ? 1 : -1;
+    return p === t || p.startsWith(`${t}/`) ? t.length : -1;
+}
+/**
+ * The active item by **longest-prefix match** over every `href` and `match` pattern, so the
+ * dashboard (`/site`) isn't active on `/site/posts`. The trail feeds Sidebar, Breadcrumb and Page header.
+ */
+export function resolveActive(nodes, path) {
+    if (!path)
+        return { trail: [] };
+    let best = { score: -1, trail: [] };
+    const visit = (items, parents) => {
+        for (const it of items) {
+            const trail = [...parents, it.id];
+            let score = it.href ? matchPath(it.href, path) : -1;
+            if (Array.isArray(it.match))
+                for (const m of it.match)
+                    score = Math.max(score, matchPath(m, path));
+            else if (typeof it.match === "function" && it.match(path))
+                score = Math.max(score, 0.5 + (it.href ? clean(it.href).length : 0));
+            // Ties go to the deeper item ("All posts" over its parent "Posts", both /site/posts).
+            if (score >= 0 && (score > best.score || (score === best.score && trail.length > best.trail.length)))
+                best = { score, trail };
+            if (it.children)
+                visit(it.children, trail);
+        }
+    };
+    visit(navItems(nodes), []);
+    return best.score < 0 ? { trail: [] } : { trail: best.trail, leafId: best.trail[best.trail.length - 1] };
+}
+/**
+ * Every navigable item (has an `href`, not disabled) as a flat list — for ⌘K "Go to" and Breadcrumb.
+ * A child whose `href` equals its parent's (an "All posts" index) is folded into the parent.
+ */
+export function flattenNav(nodes) {
+    const out = [];
+    const seen = new Set();
+    const visit = (items, labels, ids, group, icon) => {
+        for (const it of items) {
+            const trail = [...labels, it.label];
+            const idTrail = [...ids, it.id];
+            const ic = it.icon ?? icon;
+            if (it.href && !it.disabled && !seen.has(it.href)) {
+                seen.add(it.href);
+                out.push({ id: it.id, label: it.label, href: it.href, trail, ids: idTrail, group, icon: ic, keywords: it.keywords, external: it.external ?? isAbsoluteHref(it.href) });
+            }
+            if (it.children)
+                visit(it.children, trail, idTrail, group, ic);
+        }
+    };
+    for (const n of nodes) {
+        if (isNavGroup(n))
+            visit(n.items, [], [], n.label, undefined);
+        else if (isNavItem(n))
+            visit([n], [], [], undefined, undefined);
+    }
+    return out;
+}
+/** Finds an item by id anywhere in the tree. */
+export function findNavItem(nodes, id) {
+    const visit = (items) => {
+        for (const it of items) {
+            if (it.id === id)
+                return it;
+            const hit = it.children && visit(it.children);
+            if (hit)
+                return hit;
+        }
+        return undefined;
+    };
+    return visit(navItems(nodes));
+}
+/** Breadcrumb items for an active trail (`resolveActive(...).trail`). */
+export function navTrailItems(nodes, trail) {
+    return trail.map((id) => findNavItem(nodes, id)).filter((x) => Boolean(x)).map((it) => ({ id: it.id, label: it.label, href: it.href }));
+}
+/** Normalises a `BadgeSpec`; `undefined` / `0` / empty → `undefined` (nothing to show). */
+export function normaliseBadge(b) {
+    if (b == null || b === "" || b === 0)
+        return undefined;
+    if (typeof b === "number")
+        return { count: b, tone: "accent", dot: false };
+    if (typeof b === "string")
+        return { text: b, tone: "accent", dot: false };
+    if (!b.dot && !b.count && !b.label)
+        return undefined;
+    return { count: b.count, tone: b.tone ?? "accent", dot: Boolean(b.dot), label: b.label };
+}
+/** Cookie the App shell stores the collapsed state in (`"1"` = rail). Read it on the server to avoid a flash. */
+export const SIDEBAR_COOKIE = "ui-sidebar";
+/** `true` / `false` from a `ui-sidebar` cookie value (or a whole `Cookie` header); `undefined` when unset. */
+export function parseSidebarCookie(value) {
+    if (!value)
+        return undefined;
+    const m = value.includes("=") ? new RegExp(`(?:^|;\\s*)${SIDEBAR_COOKIE}=([^;]*)`).exec(value)?.[1] : value;
+    return m === "1" ? true : m === "0" ? false : undefined;
+}

package/dist/lib/provider.d.ts

@@ -0,0 +1,100 @@
+import * as React from "react";
+import { type LocaleProviderProps } from "./locale.js";
+/** Props every kit link accepts. Router links (Next `Link`) are compatible. */
+export interface VamosLinkProps extends Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, "href"> {
+    href: string;
+    /** Router hint: replace the history entry. */
+    replace?: boolean;
+    /** Router hint: prefetch the target. */
+    prefetch?: boolean | null;
+    ref?: React.Ref<HTMLAnchorElement>;
+}
+export type VamosLinkComponent = React.ComponentType<VamosLinkProps>;
+/** Props every kit image accepts. Next `Image` is compatible. */
+export interface VamosImageProps extends Omit<React.ImgHTMLAttributes<HTMLImageElement>, "src" | "alt" | "width" | "height"> {
+    src: string;
+    alt: string;
+    width?: number;
+    height?: number;
+    /** Fill the positioned parent (object-fit via className). */
+    fill?: boolean;
+    /** Above-the-fold image: eager loading + high fetch priority. */
+    priority?: boolean;
+    quality?: number;
+    ref?: React.Ref<HTMLImageElement>;
+}
+export type VamosImageComponent = React.ComponentType<VamosImageProps>;
+export interface NavigateOptions {
+    replace?: boolean;
+    scroll?: boolean;
+}
+export interface VamosContextValue {
+    Link: VamosLinkComponent;
+    Image: VamosImageComponent;
+    navigate: (href: string, options?: NavigateOptions) => void;
+    /** Current pathname, for active nav items. Pass it from the server layout to avoid a hydration flash. */
+    currentPath?: string;
+    /** Permission check used to hide nav items and actions. Hiding is not access control. */
+    can: (permission: string, resource?: unknown) => boolean;
+    /** Media adapter (see `@vamos-ui/react/media`). Typed by the consumer: `useMediaAdapter<MyAdapter>()`. */
+    media?: unknown;
+}
+/** Default link: a plain `<a>` (router hints are dropped). */
+export declare const DefaultLink: React.ForwardRefExoticComponent<Omit<VamosLinkProps, "ref"> & React.RefAttributes<HTMLAnchorElement>>;
+/** Default image: a plain `<img>` with lazy loading; `fill` covers the positioned parent. */
+export declare const DefaultImage: React.ForwardRefExoticComponent<Omit<VamosImageProps, "ref"> & React.RefAttributes<HTMLImageElement>>;
+export interface VamosProviderProps extends Omit<LocaleProviderProps, "children">, Partial<Omit<VamosContextValue, "currentPath">> {
+    currentPath?: string;
+    children: React.ReactNode;
+}
+/**
+ * The app root bridge: locale + router + image + permissions + media, set once.
+ * The kit never imports a framework; pass your router's pieces (or use `@vamos-ui/react/next`).
+ *
+ * ```tsx
+ * "use client";
+ * import Link from "next/link";
+ * import { usePathname, useRouter } from "next/navigation";
+ *
+ * export function Providers({ children }) {
+ *   const router = useRouter();
+ *   return (
+ *     <VamosProvider Link={Link} navigate={(href, o) => (o?.replace ? router.replace(href) : router.push(href))}
+ *       currentPath={usePathname()} can={(p) => user.permissions.includes(p)} locale="en-US">
+ *       {children}
+ *     </VamosProvider>
+ *   );
+ * }
+ * ```
+ */
+export declare function VamosProvider({ Link, Image, navigate, currentPath, can, media, locale, messages, dir, timeZone, currency, children }: VamosProviderProps): React.JSX.Element;
+/** The whole bridge value. */
+export declare const useVamos: () => VamosContextValue;
+/** The app's link component (default `<a>`). */
+export declare const useLink: () => VamosLinkComponent;
+/** The app's image component (default `<img>`). */
+export declare const useImage: () => VamosImageComponent;
+/** The permission check (default: everything allowed). */
+export declare const useCan: () => VamosContextValue["can"];
+/** The media adapter, typed by the caller. */
+export declare const useMediaAdapter: <T = unknown>() => T | undefined;
+/** `navigate`, `currentPath` and an `isActive(href)` helper for nav items. */
+export declare function useNavigation(): {
+    navigate: (href: string, options?: NavigateOptions) => void;
+    currentPath: string | undefined;
+    /** `exact`: only the same path; otherwise the path or any child path (`/posts` is active on `/posts/12`). */
+    isActive(href: string, options?: {
+        exact?: boolean;
+    }): boolean;
+};
+/** `true` for absolute URLs to another origin, `mailto:`, `tel:` and protocol-relative links. */
+export declare function isExternalHref(href: string): boolean;
+export interface SmartLinkProps extends VamosLinkProps {
+    /** Force external behaviour (new tab + `rel="noopener noreferrer"`). Default: detected from `href`. */
+    external?: boolean;
+}
+/**
+ * Internal links go through the app's router `Link`; external ones render `<a target="_blank" rel="noopener noreferrer">`
+ * (`mailto:` / `tel:` stay in the same tab).
+ */
+export declare const SmartLink: React.ForwardRefExoticComponent<Omit<SmartLinkProps, "ref"> & React.RefAttributes<HTMLAnchorElement>>;

package/dist/lib/provider.js

@@ -0,0 +1,105 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import * as React from "react";
+import { LocaleProvider } from "./locale.js";
+/** Default link: a plain `<a>` (router hints are dropped). */
+export const DefaultLink = React.forwardRef(function DefaultLink({ replace: _r, prefetch: _p, ...props }, ref) {
+    return _jsx("a", { ref: ref, ...props });
+});
+/** Default image: a plain `<img>` with lazy loading; `fill` covers the positioned parent. */
+export const DefaultImage = React.forwardRef(function DefaultImage({ fill, priority, quality: _q, style, loading, decoding, ...props }, ref) {
+    return (_jsx("img", { ref: ref, loading: loading ?? (priority ? "eager" : "lazy"), decoding: decoding ?? "async", fetchPriority: priority ? "high" : undefined, style: fill ? { position: "absolute", inset: 0, width: "100%", height: "100%", ...style } : style, ...props }));
+});
+const defaultNavigate = (href, o) => {
+    if (typeof window === "undefined")
+        return;
+    if (o?.replace)
+        window.location.replace(href);
+    else
+        window.location.assign(href);
+};
+const VamosContext = React.createContext({
+    Link: DefaultLink,
+    Image: DefaultImage,
+    navigate: defaultNavigate,
+    can: () => true,
+});
+/**
+ * The app root bridge: locale + router + image + permissions + media, set once.
+ * The kit never imports a framework; pass your router's pieces (or use `@vamos-ui/react/next`).
+ *
+ * ```tsx
+ * "use client";
+ * import Link from "next/link";
+ * import { usePathname, useRouter } from "next/navigation";
+ *
+ * export function Providers({ children }) {
+ *   const router = useRouter();
+ *   return (
+ *     <VamosProvider Link={Link} navigate={(href, o) => (o?.replace ? router.replace(href) : router.push(href))}
+ *       currentPath={usePathname()} can={(p) => user.permissions.includes(p)} locale="en-US">
+ *       {children}
+ *     </VamosProvider>
+ *   );
+ * }
+ * ```
+ */
+export function VamosProvider({ Link, Image, navigate, currentPath, can, media, locale, messages, dir, timeZone, currency, children }) {
+    const parent = React.useContext(VamosContext);
+    const value = React.useMemo(() => ({
+        Link: Link ?? parent.Link,
+        Image: Image ?? parent.Image,
+        navigate: navigate ?? parent.navigate,
+        currentPath: currentPath ?? parent.currentPath,
+        can: can ?? parent.can,
+        media: media ?? parent.media,
+    }), [Link, Image, navigate, currentPath, can, media, parent]);
+    return (_jsx(VamosContext.Provider, { value: value, children: _jsx(LocaleProvider, { locale: locale, messages: messages, dir: dir, timeZone: timeZone, currency: currency, children: children }) }));
+}
+/** The whole bridge value. */
+export const useVamos = () => React.useContext(VamosContext);
+/** The app's link component (default `<a>`). */
+export const useLink = () => React.useContext(VamosContext).Link;
+/** The app's image component (default `<img>`). */
+export const useImage = () => React.useContext(VamosContext).Image;
+/** The permission check (default: everything allowed). */
+export const useCan = () => React.useContext(VamosContext).can;
+/** The media adapter, typed by the caller. */
+export const useMediaAdapter = () => React.useContext(VamosContext).media;
+const normalise = (p) => (p.length > 1 ? p.replace(/\/+$/, "") : p);
+/** `navigate`, `currentPath` and an `isActive(href)` helper for nav items. */
+export function useNavigation() {
+    const { navigate, currentPath } = React.useContext(VamosContext);
+    return React.useMemo(() => ({
+        navigate,
+        currentPath,
+        /** `exact`: only the same path; otherwise the path or any child path (`/posts` is active on `/posts/12`). */
+        isActive(href, options = {}) {
+            if (!currentPath)
+                return false;
+            const path = normalise(currentPath.split(/[?#]/)[0]);
+            const target = normalise(href.split(/[?#]/)[0]);
+            if (options.exact || target === "/")
+                return path === target;
+            return path === target || path.startsWith(`${target}/`);
+        },
+    }), [navigate, currentPath]);
+}
+/** `true` for absolute URLs to another origin, `mailto:`, `tel:` and protocol-relative links. */
+export function isExternalHref(href) {
+    return /^([a-z][a-z\d+.-]*:|\/\/)/i.test(href);
+}
+/**
+ * Internal links go through the app's router `Link`; external ones render `<a target="_blank" rel="noopener noreferrer">`
+ * (`mailto:` / `tel:` stay in the same tab).
+ */
+export const SmartLink = React.forwardRef(function SmartLink({ href, external, target, rel, ...props }, ref) {
+    const Link = useLink();
+    const isExternal = external ?? isExternalHref(href);
+    if (isExternal) {
+        const newTab = !/^(mailto|tel|sms):/i.test(href);
+        const { replace: _r, prefetch: _p, ...rest } = props;
+        return _jsx("a", { ref: ref, href: href, target: target ?? (newTab ? "_blank" : undefined), rel: rel ?? (newTab ? "noopener noreferrer" : undefined), ...rest });
+    }
+    return _jsx(Link, { ref: ref, href: href, target: target, rel: rel, ...props });
+});

package/dist/lib/public.d.ts

@@ -0,0 +1,23 @@
+export { cn } from "./cn.js";
+export { LocaleProvider, useLocale, useMessages, useFormat, useText, mergeMessages, directionOf, type LocaleProviderProps, type LocaleValue, type ResolvedMessages, } from "./locale.js";
+export { useLabels, createLabels, resolveLabels, type LabelFn, type LabelValues, type LabelsProp } from "./labels.js";
+export { formatMessage } from "./message-format.js";
+export { en, type Messages, type MessagesInput } from "../locales/en.js";
+export type { Formatter } from "../format/core.js";
+export { foldText, matchText, highlightText, highlightParts, cmdkFilter, compareText, getCollator, upperText, lowerText, initials, slugify, registerTextRules, baseLanguage, type TextRules, type SlugifyOptions, } from "./text.js";
+export { useControllableState, useLatest, useEventCallback, useIsomorphicLayoutEffect, type UseControllableStateOptions } from "./use-controllable-state.js";
+export { composeRefs, useComposedRefs, mergeIds, setRef } from "./compose-refs.js";
+export { useMediaQuery, useBreakpoint, breakpoints } from "./use-media-query.js";
+export { useReducedMotion, useReducedTransparency } from "./use-reduced-motion.js";
+export { useHotkeys, useIsMac, isApplePlatform, parseShortcut, matchesShortcut, shortcutKeys, formatKey, formatShortcut, type Shortcut, type ParsedShortcut, type UseHotkeysOptions, } from "./use-hotkeys.js";
+export { useHoverIntent, type UseHoverIntentOptions } from "./use-hover-intent.js";
+export { useContainerWidth, type ContainerSize } from "./use-container-width.js";
+export { controlVariants, itemVariants, itemSlots, type ControlVariantProps, type ItemVariantProps, type MenuEntry, type MenuItemEntry, type MenuCheckboxEntry, type MenuRadioEntry, type MenuSubmenuEntry, type MenuGroupEntry, type MenuSeparatorEntry, type MenuLabelEntry, } from "./variants.js";
+export { ThemeScope, PortalContainer, usePortalContainer, themeAttributes, type ThemeAxes, type ThemeScopeProps } from "./theme-scope.js";
+export { Layer, LayerProvider, useLayerDepth, layerAttributes, type LayerProps } from "./layer.js";
+export { VamosProvider, useVamos, useLink, useImage, useCan, useNavigation, useMediaAdapter, SmartLink, DefaultLink, DefaultImage, isExternalHref, type VamosProviderProps, type VamosContextValue, type VamosLinkProps, type VamosLinkComponent, type VamosImageProps, type VamosImageComponent, type NavigateOptions, type SmartLinkProps, } from "./provider.js";
+export { useAsyncList, type AsyncLoader, type AsyncPage, type AsyncListState, type UseAsyncListOptions } from "./use-async-list.js";
+export { parseColor, toHex, formatColor, contrastRatio, contrastLevel, readableOn, type ColorFormat } from "./color.js";
+export { FieldContext, useFieldContext, useFieldControl, FieldContextReset, focusFirstInvalid, type FieldContextValue, type ControlA11yProps } from "./field-context.js";
+export { ChipRemoveButton, LocalizedText, LocaleCount, type ChipRemoveButtonProps } from "./islands.js";
+export { CopyValueButton, type CopyValueButtonProps } from "./data-islands.js";