@usequeek/theme-kit 0.1.11 → 0.1.12

package/README.md

@@ -93,6 +93,35 @@ export default function ProductPage({ product, metafieldDefinitions }: ProductPa
 - Dynamic sources (`$source` refs) resolve server-side; block data always
   reaches the theme as literals — nothing to handle.
 
+## App blocks slot
+
+Product pages render merchant-placed app blocks through the slot — never app
+code:
+
+```tsx
+import { AppBlocks } from '@usequeek/theme-kit/apps';
+
+export default function ProductPage({ product }: ProductPageProps) {
+  return <AppBlocks target="product" productId={product.slug} />;
+}
+```
+
+- MUST: place `<AppBlocks target="product" productId={...} />` on the
+  product page. `target` is product-only in phase 1 — no other slot exists.
+  `productId` scopes availability reads and deep links to the shown product;
+  omit `vendorSlug` (the host resolves the store itself).
+- The host registers its placement component once through `AppBlocksProvider`
+  (`renderBlocks`); the slot renders whatever the host registered, or nothing
+  when no provider is mounted — never an error, never a shifted layout.
+- Empty and error states render nothing: a store with no placements ships no
+  markup and fires no request; a slow or dead app collapses to its fallback
+  and never breaks the page. No app HTML/JS ever reaches the theme — blocks
+  are Queek-rendered primitives (date/time/select) plus a deep-link CTA.
+- Style only: blocks emit `core-app-block` with `__title`, `__description`,
+  `__box`, `__skeleton*`, `__fallback*`, `__field`, `__label`, `__input`,
+  `__slots`/`__slot`, `__empty`, `__cta`, `__retry` and `__image` hooks. No
+  kit CSS ships for these — style them in your theme.
+
 ## Attribution: Powered by Queek
 
 Every storefront is a billboard — every footer variant of every theme renders

package/apps.tsx

@@ -0,0 +1,49 @@
+'use client';
+
+import { createContext, useContext, type ComponentType, type JSX, type ReactNode } from 'react';
+
+/**
+ * Where a theme renders installed app blocks. Themes import this module,
+ * never app code — which framework and which storefront serves the blocks
+ * is Queek's decision, and a theme written against this slot keeps working
+ * when that changes. Only the host's registration does.
+ *
+ *   import { AppBlocks } from '@usequeek/theme-kit/apps';
+ *   <AppBlocks target="product" productId={product.slug} />
+ *
+ * The slot is deliberately presentation-free: the host registers its real
+ * placement component (fetch, loading shell, Queek-rendered blocks) through
+ * `AppBlocksProvider`, and the slot renders whatever the host registered.
+ * No provider (or none yet on the server) renders nothing — never an error,
+ * never a shifted layout.
+ */
+
+export type AppBlocksTarget = 'product';
+
+export interface AppBlocksRendererProps {
+  target: AppBlocksTarget;
+  productId?: string;
+  vendorSlug?: string;
+}
+
+export type AppBlocksRenderer = ComponentType<AppBlocksRendererProps>;
+
+const AppBlocksContext = createContext<AppBlocksRenderer | null>(null);
+
+/** The host wraps the theme tree and registers its placement component. */
+export function AppBlocksProvider({
+  renderBlocks,
+  children,
+}: {
+  renderBlocks: AppBlocksRenderer;
+  children: ReactNode;
+}): JSX.Element {
+  return <AppBlocksContext.Provider value={renderBlocks}>{children}</AppBlocksContext.Provider>;
+}
+
+/** The theme-facing slot: renders the host's component, or nothing. */
+export function AppBlocks({ target, productId, vendorSlug }: AppBlocksRendererProps): JSX.Element | null {
+  const RenderBlocks = useContext(AppBlocksContext);
+  if (RenderBlocks === null) return null;
+  return <RenderBlocks target={target} productId={productId} vendorSlug={vendorSlug} />;
+}

package/client.ts

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

package/package.json

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

package/tests/apps.test.tsx

@@ -0,0 +1,33 @@
+import React from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { describe, expect, it } from 'vitest';
+import * as apps from '../apps';
+import { AppBlocks, AppBlocksProvider } from '../apps';
+
+describe('apps — the theme-facing app-block slot', () => {
+  it('is exactly the provider, the slot, and the shared types', () => {
+    expect(Object.keys(apps).sort()).toEqual(['AppBlocks', 'AppBlocksProvider']);
+  });
+
+  it('renders nothing without a host registration (SSR-safe)', () => {
+    const html = renderToStaticMarkup(
+      React.createElement(AppBlocks, { target: 'product', productId: 'p1' }),
+    );
+
+    expect(html).toBe('');
+  });
+
+  it('renders whatever the host registered, with the slot props', () => {
+    function HostBlocks({ target, productId }: { target: 'product'; productId?: string }) {
+      return <div data-host-blocks={`${target}:${productId ?? ''}`} />;
+    }
+
+    const html = renderToStaticMarkup(
+      <AppBlocksProvider renderBlocks={HostBlocks}>
+        <AppBlocks target="product" productId="p1" vendorSlug="glow" />
+      </AppBlocksProvider>,
+    );
+
+    expect(html).toContain('data-host-blocks="product:p1"');
+  });
+});