@usequeek/theme-kit 0.1.7 → 0.1.8

package/README.md

@@ -54,6 +54,80 @@ Theme CSS ships with the package: `@usequeek/theme-kit/shared-blocks/core-blocks
   source. Anyone testing a theme with vitest needs the same `inline` line;
   anyone compiling one needs `moduleResolution: bundler` + `jsx: react-jsx`.
 
+## Custom data: metafields & metaobjects
+
+Product pages receive custom data already resolved — never fetch it:
+
+```tsx
+import { ProductMetafields } from '@usequeek/theme-kit/components/product-metafields';
+import type { ProductPageProps } from '@usequeek/theme-kit/types/theme';
+
+export default function ProductPage({ product, metafieldDefinitions }: ProductPageProps) {
+  return <ProductMetafields product={product} definitions={metafieldDefinitions} />;
+}
+```
+
+- MUST: place `<ProductMetafields product definitions={metafieldDefinitions} />`
+  on the product page. `product.metafields` (`types/product.ts`) arrives as
+  presented values — a scalar, scalar list, `MetaobjectEntry`, or
+  `MetaobjectEntry[]`; labels come via `metafieldDefinitions` (unknown keys
+  fall back to a humanised key). The component renders nothing when there is
+  nothing visible to show.
+- MAY: compose your own layout with the exported `EntryCard` and `renderValue`
+  from the same module instead of placing the section.
+- Style only: the section emits `core-metafields*` classes (`core-metafields`,
+  `__field`, `__label`, `__value`, `__text`, `__link`, `__image`, `__pre`,
+  `__list`, `__list-item`, `__entry-card`, `__entry-title`, `__entry-field`,
+  `__entry-field-label`, `__entry-field-value`, `__entry-grid`);
+  `DefaultMetaobjectPage` emits `core-metaobject-page*`. No kit CSS ships for
+  these — style them in your theme.
+- The `metaobjects` section block (`shared-blocks/metaobjects`,
+  framework-owned) renders a merchant-picked type's entries when the page
+  supplies its data; it emits `core-block-metaobjects` with `--grid`/`--list`
+  modifiers, `core-block-metaobjects__list` with `--grid`/`--list` variants,
+  plus `__title` and `__card-link`. Never re-implement it — style the classes.
+- Optional entry pages: provide `pages.Metaobject: FC<MetaobjectPageProps>`
+  (`entry` plus `definition { type; name; fields: [{ key; name; type }] }`).
+  When absent, core `DefaultMetaobjectPage`
+  (`components/default-metaobject-page`) is used.
+- Dynamic sources (`$source` refs) resolve server-side; block data always
+  reaches the theme as literals — nothing to handle.
+
+## Attribution: Powered by Queek
+
+Every storefront is a billboard — every footer variant of every theme renders
+the core-owned attribution link:
+
+```tsx
+import { PoweredByQueek } from '@usequeek/theme-kit/components/powered-by-queek';
+
+export default function Footer() {
+  return (
+    <footer>
+      {/* ... */}
+      <PoweredByQueek />
+    </footer>
+  );
+}
+```
+
+- MUST: place `<PoweredByQueek />` on every footer variant (`footers/*.tsx`,
+  or `footer.tsx` where a theme has no `footers/` dir). The placement and
+  spacing are the theme's — the component is the content, the footer owns
+  where it sits. `theme-check` rule `theme/footer-shows-powered-by` enforces
+  this, so a theme cannot ship without it.
+- Style only: the link emits `core-powered-by` with a
+  `core-powered-by__brand` hook on the `Queek` wordmark; an optional
+  `className` passthrough lets a footer position it (e.g.
+  `<PoweredByQueek className="my-footer__powered" />`). No kit CSS ships for
+  it — style the classes in your theme.
+- The href (`https://usequeek.com/business`), `target="_blank"` and
+  `rel="noopener noreferrer"` are the contract — never re-implement the
+  markup by hand.
+- `hidden` (default false) takes the component's visibility from a prop as
+  the seam for a possible future plan perk. There is no merchant-facing
+  toggle for it in v1 — always render it visible.
+
 ## Boundary
 
 The kit must never import the storefront app, its themes, or `lib/storefront`.

package/client.ts

@@ -13,6 +13,7 @@ export * from './shared-blocks';
 export * from './components/blog';
 export * from './components/image';
 export * from './components/product-metafields';
+export * from './components/powered-by-queek';
 export * from './components/default-metaobject-page';
 export * from './components/product-media-frame';
 export * from './components/variant-picker';

package/components/powered-by-queek.tsx

@@ -0,0 +1,36 @@
+import type { JSX } from 'react';
+
+export interface PoweredByQueekProps {
+  /** Extra class so a footer can position the link — styling stays theme-owned. */
+  className?: string;
+  /**
+   * Reserved for a future plan perk (paid removal). Defaults to false and is
+   * always rendered in v1 — there is no merchant-facing toggle for it.
+   */
+  hidden?: boolean;
+}
+
+/**
+ * Core-owned storefront attribution — the `ProductMetafields` pattern: themes
+ * import-and-place it, never re-implement it.
+ *
+ * Required on every footer variant of every theme (enforced by `theme-check`
+ * rule `theme/footer-shows-powered-by` in the storefront repo). The link
+ * target (`https://usequeek.com/business`) and `rel` are the contract —
+ * do not change them. Markup carries `core-powered-by` classes so each theme
+ * styles it in its own `theme.css`; no kit CSS ships for it.
+ */
+export function PoweredByQueek({ className, hidden = false }: PoweredByQueekProps): JSX.Element | null {
+  if (hidden) return null;
+
+  return (
+    <a
+      href="https://usequeek.com/business"
+      target="_blank"
+      rel="noopener noreferrer"
+      className={className ? `core-powered-by ${className}` : 'core-powered-by'}
+    >
+      Powered by <strong className="core-powered-by__brand">Queek</strong>
+    </a>
+  );
+}

package/package.json

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

package/tests/powered-by-queek.test.tsx

@@ -0,0 +1,37 @@
+import React from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { describe, expect, it } from 'vitest';
+import { PoweredByQueek } from '../components/powered-by-queek';
+
+function render(props?: { className?: string; hidden?: boolean }): string {
+  return renderToStaticMarkup(React.createElement(PoweredByQueek, props));
+}
+
+describe('PoweredByQueek', () => {
+  it('links to the Queek business page with the attribution contract intact', () => {
+    const html = render();
+
+    expect(html).toContain('<a');
+    expect(html).toContain('href="https://usequeek.com/business"');
+    expect(html).toContain('target="_blank"');
+    expect(html).toContain('rel="noopener noreferrer"');
+  });
+
+  it('renders "Powered by Queek" with the brand hook for theme styling', () => {
+    const html = render();
+
+    expect(html).toContain('core-powered-by');
+    expect(html).toContain('Powered by');
+    expect(html).toContain('<strong class="core-powered-by__brand">Queek</strong>');
+  });
+
+  it('passes a footer positioning class through alongside the core class', () => {
+    const html = render({ className: 'qn-footer4__powered' });
+
+    expect(html).toContain('class="core-powered-by qn-footer4__powered"');
+  });
+
+  it('renders nothing when hidden', () => {
+    expect(render({ hidden: true })).toBe('');
+  });
+});