@dreamtree-org/landing-kit 0.0.0-stage → 0.2.0

package/index.d.ts

@@ -0,0 +1,224 @@
+import type { ComponentType, CSSProperties, ReactElement, ReactNode } from 'react';
+
+/** Products with a built-in brand entry. */
+export type BrandId =
+  | 'billpro'
+  | 'taskpro'
+  | 'venturepro'
+  | 'campaignpro'
+  | 'firepro'
+  | 'procurementpro'
+  | 'fitweavepro'
+  | 'aiagentbuilder'
+  | 'runloompro'
+  | 'appforge';
+
+export interface Brand {
+  id: string;
+  name: string;
+  /** Drives every derived shade: panel, links, focus. Any CSS colour. */
+  primary: string;
+  /** Mark tile, bullet dots. Defaults to primary. */
+  accent?: string | undefined;
+  /** Override the derived brand-panel colour. */
+  panel?: string | undefined;
+  /** Square logo mark URL. Falls back to `mark`, then a monogram tile. */
+  logoSrc?: string | undefined;
+  mark?: ReactNode;
+  headline: string;
+  pitch?: string | undefined;
+  points?: string[] | undefined;
+  /** Small line at the bottom of the brand panel. */
+  category?: string | undefined;
+  platformHeadline?: string | undefined;
+  platformPitch?: string | undefined;
+}
+
+export interface LegalLink {
+  label: string;
+  href: string;
+}
+
+export interface AuthShellProps {
+  brand: Brand;
+  title: ReactNode;
+  subtitle?: ReactNode;
+  children?: ReactNode;
+  footer?: ReactNode;
+  /** 'platform' = super-admin door: darker panel + "Platform" badge. */
+  variant?: 'tenant' | 'platform' | undefined;
+  legalLinks?: LegalLink[] | undefined;
+  /** react-router `Link` or next/link; receives both `to` and `href`. */
+  linkComponent?: ComponentType<any> | undefined;
+  className?: string | undefined;
+}
+
+export declare function AuthShell(props: AuthShellProps): ReactElement;
+export declare function brandStyle(brand: Brand): CSSProperties;
+export declare const brands: Record<string, Brand>;
+export declare function getBrand(id: BrandId | (string & {})): Brand;
+
+/** A lucide-react style component (`Receipt`) or an element (`<Receipt />`). */
+export type Icon = ComponentType<any> | ReactElement;
+export interface NavLink { label: string; href: string; reload?: boolean }
+export interface Item { title: string; body?: string; icon?: Icon; href?: string; /** small kicker above the title (cards) */ label?: string }
+export interface QA { q: string; a: string }
+export interface Step { name: string; text: string }
+/** `{ label, href }` is a link; `{ label, demo: true }` (or a string) opens "Book a demo". */
+export type CtaSpec = string | { label: string; href?: string; demo?: boolean };
+
+export interface HeroProps {
+  eyebrow?: ReactNode;
+  /** A string, or `[lead, highlight]` to underline the second half. */
+  title: ReactNode | [ReactNode, ReactNode];
+  subtitle?: ReactNode;
+  lead?: ReactNode;
+  chips?: string[];
+  chipsLabel?: string;
+  /** Button label; `false`/'' hides the button. Default 'Book a demo'. */
+  cta?: ReactNode;
+  secondary?: NavLink;
+  overlap?: boolean;
+  id?: string;
+  /** A decorative node (illustration) laid behind the hero copy, aria-hidden. */
+  backdrop?: ReactNode;
+}
+
+export type FeatureVariant = 'cards' | 'split' | 'list' | 'intro' | 'highlight' | 'band' | 'compare' | 'links' | 'detail';
+export type Tone = 'plain' | 'tinted' | 'muted' | 'dark';
+
+export interface FeatureSectionProps {
+  id?: string;
+  variant?: FeatureVariant;
+  tone?: Tone;
+  eyebrow?: ReactNode;
+  title: ReactNode;
+  body?: ReactNode;
+  items?: Array<Item | string>;
+  /** One call to action or several side by side. */
+  cta?: CtaSpec | CtaSpec[];
+  footnote?: ReactNode;
+  /** split · band · highlight: your own node on the visual side (items then show as an icon row under the text). */
+  media?: ReactNode;
+  /** Visual side first. */
+  reverse?: boolean;
+  /** intro */ subtitle?: ReactNode; detail?: ReactNode; note?: ReactNode; glance?: string[]; glanceTitle?: string; glanceNote?: ReactNode; link?: NavLink;
+  /** highlight */ noteLabel?: string;
+  /** band */ examples?: string[]; examplesLabel?: string;
+  /** compare */ columns?: Array<{ title: string; items: string[]; tone?: 'good' | 'check' }>;
+  /** split, detail: a checklist under the text */ bullets?: string[];
+}
+
+export interface AudiencesProps {
+  id?: string; eyebrow?: ReactNode; title: ReactNode; body?: ReactNode; tone?: Tone; linkLabel?: string;
+  items: Array<{
+    id?: string; keyword?: string; title: string; body: string; href?: string; linkLabel?: string; icon?: Icon;
+    /** decorative illustration beside the heading */ media?: ReactNode;
+    /** a short icon list under the text */ features?: Array<string | { title: string; icon?: Icon }>;
+  }>;
+}
+export interface HowItWorksProps { id?: string; eyebrow?: ReactNode; title: ReactNode; body?: ReactNode; steps?: Step[]; items?: Step[]; tone?: Tone; cta?: CtaSpec | CtaSpec[]; /** seo only */ howToName?: string }
+export interface FaqProps { id?: string; eyebrow?: ReactNode; title?: ReactNode; intro?: ReactNode; items: QA[]; openFirst?: boolean; tone?: Tone }
+export interface DemoCtaProps {
+  id?: string; eyebrow?: ReactNode; title: ReactNode; body?: ReactNode; label?: ReactNode; chips?: string[]; chipsLabel?: string;
+  /** a "what to tell us" box under the button */ note?: { title?: ReactNode; body?: ReactNode };
+  /** a quiet link under it, e.g. { label: 'Already have a workspace? Log in', href: '/login', reload: true } */ link?: NavLink;
+}
+export interface FooterProps {
+  blurb?: ReactNode;
+  columns?: Array<{ title: string; label?: string; links: NavLink[]; compact?: boolean }>;
+  org?: string; tagline?: string; legal?: NavLink[]; year?: number; brand?: Brand;
+}
+
+export interface LandingContent {
+  product?: { name?: string; definition?: string; description?: string; features?: string[]; [k: string]: unknown };
+  nav?: NavLink[];
+  /** `null` hides "Log in". Default { label: 'Log in', href: '/login' }. */
+  login?: NavLink | null;
+  header?: { cta?: ReactNode };
+  hero: HeroProps;
+  /** FeatureSection props, `{ use: 'audiences' | 'steps' | 'faq' | 'cta' | 'preview' | <slot name> }`, or an element. */
+  sections?: Array<FeatureSectionProps | { use: string } | ReactElement>;
+  audiences?: AudiencesProps;
+  steps?: HowItWorksProps;
+  faq?: FaqProps;
+  cta?: DemoCtaProps;
+  /** `false` hides the footer. */
+  footer?: FooterProps | false;
+}
+
+export interface LayoutProps {
+  brand: Brand;
+  /** react-router `Link` or next/link; receives both `to` and `href`. */
+  linkComponent?: ComponentType<any> | null;
+  /** Called with the clicked button when the page is hydrated. Un-hydrated pages use enhanceLanding(). */
+  onBookDemo?: ((trigger: HTMLElement) => void) | null;
+  /** false on sub-pages: header `#section` links become `/#section`. */
+  home?: boolean;
+  className?: string;
+}
+
+export interface LandingPageProps extends LayoutProps {
+  content: LandingContent;
+  preview?: ReactNode;
+  /** A product's own sections, placed by `{ use: '<name>' }` in content.sections (content stays data). */
+  slots?: Record<string, ReactNode>;
+}
+export interface MarketingLayoutProps extends LayoutProps {
+  nav?: NavLink[]; login?: NavLink | null; cta?: ReactNode; footer?: FooterProps | false; children?: ReactNode;
+}
+
+export interface DemoField {
+  name: string; label: string;
+  type?: 'text' | 'tel' | 'email' | 'number' | 'select' | 'textarea';
+  required?: boolean; options?: Array<{ value: string; label: string }>;
+  placeholder?: string; maxLength?: number; min?: number; rows?: number;
+  autoComplete?: string; inputMode?: string; wide?: boolean;
+}
+export interface DemoDialogProps {
+  brand?: Brand;
+  open?: boolean;
+  onClose?: () => void;
+  /** POST the request; throw an Error whose message is shown to the visitor. */
+  onSubmit: (data: Record<string, string> & { consent: true; website: string; source_path: string }) => Promise<unknown>;
+  fields?: DemoField[];
+  title?: ReactNode; intro?: ReactNode;
+  fiduciary?: string; consentText?: ReactNode; privacyHref?: string | null; policyVersion?: string;
+  submitLabel?: ReactNode; successMessage?: ReactNode | ((form: Record<string, string>) => ReactNode);
+  /** Inline errors before submit: { field: message }, empty when valid. With it, the button only waits for consent.
+   *  An Error thrown by onSubmit with `fields` shows those messages under their fields too. */
+  validate?: (form: Record<string, string>) => Record<string, string> | null | undefined;
+}
+
+export declare function LandingPage(props: LandingPageProps): JSX.Element;
+export declare function MarketingLayout(props: MarketingLayoutProps): JSX.Element;
+export declare function Header(props: { nav?: NavLink[]; login?: NavLink | null; cta?: ReactNode; brand?: Brand }): JSX.Element;
+export declare function Hero(props: HeroProps): JSX.Element;
+export declare function PreviewFrame(props: { id?: string; heading?: string; caption?: string; meta?: ReactNode; badge?: ReactNode; brand?: Brand; children?: ReactNode }): JSX.Element;
+export declare function FeatureSection(props: FeatureSectionProps): JSX.Element;
+export declare function Audiences(props: AudiencesProps): JSX.Element;
+export declare function HowItWorks(props: HowItWorksProps): JSX.Element;
+export declare function Faq(props: FaqProps): JSX.Element;
+export declare function DemoCta(props: DemoCtaProps): JSX.Element;
+export declare function DemoDialog(props: DemoDialogProps): JSX.Element | null;
+export declare const DEFAULT_DEMO_FIELDS: DemoField[];
+export declare function DreamtreeFooter(props: FooterProps): JSX.Element;
+export declare function DreamtreeMark(props: { size?: number }): JSX.Element;
+export declare function PageHero(props: { breadcrumbs?: Array<{ label: string; href?: string }>; eyebrow?: ReactNode; title: ReactNode; lead?: ReactNode; cta?: ReactNode; secondary?: NavLink }): JSX.Element;
+export declare function Breadcrumbs(props: { items: Array<{ label: string; href?: string }> }): JSX.Element | null;
+export declare function BookDemoButton(props: { size?: 'sm' | 'md' | 'lg'; variant?: 'primary' | 'inverse' | 'outline'; className?: string; children?: ReactNode; onClick?: (e: any) => void }): JSX.Element;
+export declare function BrandLockup(props: { brand?: Brand; byline?: string; href?: string }): JSX.Element | null;
+export declare function BrandMark(props: { brand: Brand; size?: number }): JSX.Element;
+export declare function Wordmark(props: { name: string }): JSX.Element;
+export declare function Section(props: { id?: string; labelledBy?: string; tone?: Tone; className?: string; narrow?: boolean; children?: ReactNode }): JSX.Element;
+export declare function SectionIntro(props: { id: string; eyebrow?: ReactNode; title: ReactNode; body?: ReactNode; align?: 'start' | 'center'; children?: ReactNode }): JSX.Element;
+export declare function Wrap(props: { className?: string; narrow?: boolean; children?: ReactNode }): JSX.Element;
+export declare function Eyebrow(props: { className?: string; children?: ReactNode }): JSX.Element | null;
+export declare function TextLink(props: { href: string; className?: string; children?: ReactNode; [k: string]: unknown }): JSX.Element;
+export declare function Cta(props: { cta?: CtaSpec; className?: string }): JSX.Element | null;
+export declare function SmartLink(props: { href: string; reload?: boolean; className?: string; children?: ReactNode; [k: string]: unknown }): JSX.Element;
+export declare function resolveHref(href: string, home: boolean): string;
+export declare const LandingProvider: import('react').Provider<{ brand: Brand | null; linkComponent?: ComponentType<any> | null; onBookDemo?: ((t: HTMLElement) => void) | null; home?: boolean }>;
+export declare function useLanding(): { brand: Brand | null; linkComponent: ComponentType<any> | null; onBookDemo: ((t: HTMLElement) => void) | null; home: boolean };
+/** The "Book a demo" island for an un-hydrated page: React mounts on first open. */
+export declare function createDemoIsland(props: Omit<DemoDialogProps, 'onClose'> | (() => Omit<DemoDialogProps, 'onClose'>)): { openDemo(trigger?: HTMLElement | null): void; close(): void };

package/package.json

@@ -1,6 +1,96 @@
 {
   "name": "@dreamtree-org/landing-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "The shared marketing site and auth frame (AuthShell + brands) for every Dreamtree product: content-driven landing pages, login/signup shell, Express routes, prerender and SEO files.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dreamtree-org/dreamtree-org.landing-kit.git"
+  },
+  "homepage": "https://github.com/dreamtree-org/dreamtree-org.landing-kit#readme",
+  "bugs": {
+    "url": "https://github.com/dreamtree-org/dreamtree-org.landing-kit/issues"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./auth": {
+      "types": "./auth.d.ts",
+      "import": "./dist/auth.js",
+      "require": "./dist/auth.cjs"
+    },
+    "./server": {
+      "types": "./server.d.ts",
+      "import": "./dist/server.js",
+      "require": "./dist/server.cjs"
+    },
+    "./seo": {
+      "types": "./seo.d.ts",
+      "import": "./dist/seo.js",
+      "require": "./dist/seo.cjs"
+    },
+    "./enhance": {
+      "types": "./enhance.d.ts",
+      "import": "./dist/enhance.js",
+      "require": "./dist/enhance.cjs"
+    },
+    "./styles.css": "./styles.css",
+    "./auth.css": "./auth.css"
+  },
+  "sideEffects": [
+    "*.css"
+  ],
+  "files": [
+    "dist",
+    "styles.css",
+    "auth.css",
+    "index.d.ts",
+    "auth.d.ts",
+    "server.d.ts",
+    "seo.d.ts",
+    "enhance.d.ts",
+    "README.md",
+    "MIGRATION.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node build.mjs",
+    "test": "node build.mjs && node --test test/*.test.mjs",
+    "prepublishOnly": "npm test",
+    "test:viewports": "node build.mjs && node test/viewports.mjs"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "devDependencies": {
+    "esbuild": "^0.25.0",
+    "express": "^4.22.3",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "react",
+    "landing-page",
+    "marketing",
+    "seo",
+    "json-ld",
+    "llms.txt",
+    "express",
+    "prerender",
+    "dreamtree"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/seo.d.ts

@@ -0,0 +1,50 @@
+export declare const SITE_PLACEHOLDER: '__SITE_URL__';
+export declare const AI_CRAWLERS: string[];
+export declare const DEFAULT_PRIVATE_PATHS: string[];
+export declare const PRIVATE_ROBOTS: string;
+export interface Locale { lang: string; og: string; country?: string }
+export declare const DEFAULT_LOCALE: Locale;
+
+export interface SeoProduct {
+  name: string;
+  /** The one-sentence definition answer engines quote. */
+  definition: string;
+  description?: string;
+  logo?: string;
+  image?: string | { path: string; width?: number; height?: number; alt?: string; type?: string };
+  /** SoftwareApplication.screenshot (a path or URL) */
+  screenshot?: string;
+  category?: string;
+  subCategory?: string;
+  operatingSystem?: string;
+  audience?: string;
+  features?: string[];
+  /** Adds an Offer with no price ("Contact us for pricing"). Off by default. */
+  offers?: { description?: string; url?: string };
+}
+export interface SeoOrg { name: string; logo?: string; email?: string; sameAs?: string[] }
+export interface SeoPage { path: string; title?: string; description?: string; name?: string; summary?: string; priority?: string; changefreq?: string; faq?: Array<{ q: string; a: string }> }
+/** The origin; SITE_PLACEHOLDER (default) when the server fills it in, null for a graph without URLs. */
+export type Site = string | null;
+
+export declare function escapeHtml(value: unknown): string;
+export declare function jsonLdScript(graph: unknown): string;
+export declare function pageUrl(path?: string, site?: Site): string | undefined;
+export declare function buildJsonLd(args: {
+  site?: Site; product: SeoProduct; org?: SeoOrg; page?: SeoPage;
+  faq?: Array<{ q: string; a: string }>;
+  howTo?: { name?: string; description?: string; steps: Array<{ name: string; text: string }>; anchor?: string } | null;
+  breadcrumbs?: Array<[string, string]>; parts?: Array<{ path: string; name?: string }>;
+  keywords?: string[]; lastmod?: string; speakable?: string[]; locale?: Locale;
+}): { '@context': 'https://schema.org'; '@graph': Array<Record<string, unknown>> };
+export declare function contentFacts(content: unknown): {
+  faq: Array<{ q: string; a: string }>;
+  howTo: { name?: string; description?: string; steps: Array<{ name: string; text: string }>; anchor: string } | null;
+  features: string[];
+  sections: Array<[string, string]>;
+};
+export declare function buildHead(args: { site?: Site; page: SeoPage; product: SeoProduct; twitterHandle?: string; jsonLd?: unknown; locale?: Locale; robots?: string }): string;
+export declare function buildRobots(args?: { site?: Site; privatePaths?: string[]; crawlers?: string[] }): string;
+export declare function buildSitemap(args: { site?: Site; pages: SeoPage[]; lastmod?: string; changefreq?: string }): string;
+export declare function buildLlmsTxt(args: { site?: Site; product: SeoProduct; org?: SeoOrg; pages?: SeoPage[]; about?: string; facts?: string[]; optional?: Array<{ label: string; path: string }> }): string;
+export declare function buildLlmsFullTxt(args: { site?: Site; product: SeoProduct; org?: SeoOrg; pages?: SeoPage[]; sections?: (page: SeoPage) => Array<[string, string]> }): string;

package/server.d.ts

@@ -0,0 +1,43 @@
+export * from './seo';
+
+type Req = { headers: Record<string, string | string[] | undefined>; protocol?: string; [k: string]: any };
+
+export declare const CRAWLER_FILES: Record<string, string>;
+export declare function siteUrl(req: Req, opts?: { appUrl?: string }): string;
+export declare function readCookie(req: Req, name: string): string | null;
+export declare function sessionCheck(opts: { cookie?: string | null; bearer?: boolean; verify: (token: string) => boolean }): (req: Req) => boolean;
+export declare function verificationTags(env?: Record<string, string | undefined>): string;
+export declare function fillSite(body: string, origin: string, opts?: { html?: boolean; env?: Record<string, string | undefined> }): string;
+
+export interface LandingRoutesOptions {
+  /** client/dist */
+  dist: string;
+  /** Default 'landing-pages.json'. Its paths are relative to its own directory. */
+  manifest?: string;
+  /** May return a Promise (e.g. a cached registry lookup). */
+  isPublicHost?: (req: any) => boolean | Promise<boolean>;
+  hasSession?: (req: any) => boolean;
+  /** 'next' (default) falls through to the SPA; 'app-shell' sends dist/index.html. */
+  onSession?: 'next' | 'app-shell';
+  /** What `/` does on a host that is not public. Default 'next'. */
+  onPrivateHost?: 'next' | 'app-shell';
+  /** 'redirect' (default): /features/ → 301 /features. 'serve': 200 at both. */
+  trailingSlash?: 'redirect' | 'serve';
+  /** The prerendered files' own URLs: 'not-found' (default, 404) or 'redirect' (301 to the page's path). */
+  rawFiles?: 'not-found' | 'redirect';
+  redirects?: Record<string, string>;
+  cacheControl?: string;
+  crawlerCache?: string;
+  privateRobots?: string;
+  appUrl?: string;
+  env?: Record<string, string | undefined>;
+}
+export declare function landingRoutes(app: any, options: LandingRoutesOptions | string): string[];
+export declare function pageFile(path: string, opts?: { homeFile?: string; pagesDir?: string }): string;
+export declare function prerenderPages(args: {
+  dist: string;
+  template?: string;
+  pages: Array<{ path: string; html: string; title?: string; description?: string; jsonLd?: unknown; head?: string }>;
+  files?: Record<string, string | null | undefined>;
+  homeFile?: string; pagesDir?: string; manifest?: string; slot?: string;
+}): { manifest: Record<string, string>; bytes: number };