@usequeek/theme-kit 0.1.9 → 0.1.10

package/README.md

@@ -128,10 +128,25 @@ export default function Footer() {
   the seam for a possible future plan perk. There is no merchant-facing
   toggle for it in v1 — always render it visible.
 
+## Links and navigation
+
+```ts
+import { Link, useRouter, usePathname } from '@usequeek/theme-kit/navigation';
+```
+
+A theme links and navigates through these, never through `next/link` or
+`next/navigation`. Which framework runs the storefront is Queek's decision: the
+kit is the one place that knows it, so a change there is a kit release, not an
+update to every theme. `Link` is an `<a>` that moves inside the store without a
+full page load (`href`, `prefetch`, `replace`, plus any anchor attribute);
+`useRouter()` gives `push`, `replace`, `back` and `refresh`; `usePathname()`
+returns the current path. The theme check rejects a theme that imports `next`.
+
 ## Boundary
 
 The kit must never import the storefront app, its themes, or `lib/storefront`.
-That one-way rule is what makes this package extractable at all.
+That one-way rule is what makes this package extractable at all. The reverse
+also holds for the framework: the kit may import `next`, a theme may not.
 
 ## Develop
 

package/client.ts

@@ -6,6 +6,7 @@
  */
 
 export * from './provider';
+export * from './navigation';
 export * from './page-renderer';
 export * from './edit-mode';
 export * from './theme-variant-resolver';

package/navigation.tsx

@@ -0,0 +1,58 @@
+'use client';
+
+/**
+ * How a theme links and moves between pages. Themes import these, never
+ * `next/link` or `next/navigation`: which framework runs the storefront is
+ * Queek's decision, and a theme written against this module keeps working
+ * when that changes — only this file does.
+ *
+ *   import { Link, useRouter, usePathname } from '@usequeek/theme-kit/navigation';
+ *
+ * The surface is deliberately small (what every theme so far has needed).
+ * Ask for an addition rather than reaching past it to the framework.
+ */
+import NextLink from 'next/link';
+import { usePathname as useFrameworkPathname, useRouter as useFrameworkRouter } from 'next/navigation';
+import { useMemo, type AnchorHTMLAttributes, type ReactNode, type Ref } from 'react';
+
+export interface LinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> {
+  /** A path inside the store (`menuItemToHref()`, `useHref()`) or a full URL. */
+  href: string;
+  /** Load the page in the background before it is clicked. Leave unset and the storefront decides. */
+  prefetch?: boolean;
+  /** Replace the current history entry instead of adding one. */
+  replace?: boolean;
+  ref?: Ref<HTMLAnchorElement>;
+  children?: ReactNode;
+}
+
+/** An `<a>` that moves inside the store without a full page load. */
+export function Link({ href, prefetch, replace, ...anchor }: LinkProps) {
+  return <NextLink href={href} prefetch={prefetch} replace={replace} {...anchor} />;
+}
+
+export interface Router {
+  /** Go to `href`, adding a history entry. */
+  push(href: string): void;
+  /** Go to `href`, replacing the current history entry. */
+  replace(href: string): void;
+  back(): void;
+  /** Re-render the current page with fresh data from the server. */
+  refresh(): void;
+}
+
+/** Move between pages from code — after a form submits, a filter changes, a search runs. */
+export function useRouter(): Router {
+  const router = useFrameworkRouter();
+  return useMemo(() => ({
+    push: (href: string) => router.push(href),
+    replace: (href: string) => router.replace(href),
+    back: () => router.back(),
+    refresh: () => router.refresh(),
+  }), [router]);
+}
+
+/** The current path, e.g. `/medley/shop` — to mark the active menu item. */
+export function usePathname(): string {
+  return useFrameworkPathname() ?? '';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usequeek/theme-kit",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "private": false,
   "license": "MIT",
   "description": "The framework a Queek storefront theme is built against.",

package/tests/navigation.test.tsx

@@ -0,0 +1,30 @@
+import React from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { describe, expect, it } from 'vitest';
+import * as navigation from '../navigation';
+import { Link } from '../navigation';
+
+describe('navigation — what a theme links and navigates with', () => {
+  it('is exactly Link, useRouter and usePathname', () => {
+    expect(Object.keys(navigation).sort()).toEqual(['Link', 'usePathname', 'useRouter']);
+  });
+
+  it('renders Link as a plain anchor carrying its href, class and children', () => {
+    const html = renderToStaticMarkup(
+      React.createElement(Link, { href: '/medley/shop', className: 'md-nav__link', 'aria-current': 'page' }, 'Shop'),
+    );
+
+    expect(html).toContain('<a');
+    expect(html).toContain('href="/medley/shop"');
+    expect(html).toContain('class="md-nav__link"');
+    expect(html).toContain('aria-current="page"');
+    expect(html).toContain('>Shop</a>');
+  });
+
+  it('keeps a full URL as is', () => {
+    const html = renderToStaticMarkup(React.createElement(Link, { href: 'https://usequeek.com/business', target: '_blank' }, 'Queek'));
+
+    expect(html).toContain('href="https://usequeek.com/business"');
+    expect(html).toContain('target="_blank"');
+  });
+});